Query Scopes
Definition
Query scopes are a way to encapsulate query constraints in your entities while giving them readable names .
A Practical Example
For instance, let's say that you need to write a report for subscribers to your site. Maybe you track subscribers in a users
table with a boolean flag in a subscribed
column. Additionally, you want to see the oldest subscribers first. You keep track of when a user subscribed in a subscribedDate
column. Your query might look as follows:
Now nothing is wrong with this query. It retrieves the data correctly and you continue on with your day.
Later, you need to retrieve a list of subscribed users for a different part of the site. So, you write a query like this:
We've duplicated the logic for how to retrieve active users now. If the database representation changed, we'd have to change it in multiple places. For instance, what if instead of keeping track of a boolean flag in the database, we just checked that the subscribedDate
column wasn't null?
Now we see the problem. Let's look at the solution.
The key here is that we are trying to retrieve subscribed users. Let's add a scope to our User
entity for subscribed
:
Now, we can use this scope in our query:
We can use this on our first example as well, for our report.
We've successfully encapsulated our concept of a subscribed user!
We can add as many scopes as we'd like. Let's add one for longestSubscribers
.
Now our query is as follows:
Best of all, we can reuse those scopes anywhere we see fit without duplicating logic.
Usage
All query scopes are methods on an entity that begin with the scope
keyword. You call these functions without the scope
keyword (as shown above).
Each scope is passed the query
, a reference to the current QueryBuilder
instance, as the first argument. Any other arguments passed to the scope will be passed in order after that.
Global Scopes
Occasionally, you want to apply a scope to each retrieval of an entity. An example of this is an Admin entity which is just a User entity with a type of admin. Global Scopes can be registered in the applyGlobalScopes
method on an entity. Inside this entity you can call any number of scopes:
These scopes will be applied to the query without needing to call the scope again.
If you have a global scope applied to an entity that you need to temporarily disable, you can disable them individually using the withoutGlobalScope
method:
Subselects
Subselects are a useful way to grab data from related tables without having to execute the full relationship. Sometimes you just want a small piece of information like the last_login_date
of a user, not the entire Login
relationship. Subselects are perfect for this use case. You can even use subselects to provide the correct key for subselect relationships. We'll show how both work here.
Quick handles subselect properties (or computed or formula properties) through query scopes. This allows you to dynamically include a subselect. If you would like to always include a subselect, add it to your entity's list of global scopes.
Here's an example of grabbing the last_login_date
for a User:
We'd add this subselect by calling our scope:
In this example, we are using the addSubselect
helper method. Here is that function signature:
You might be wondering why not use the logins
relationship? Or even logins().latest().limit( 1 ).get()
? Because that executes a second query. Using a subselect we get all the information we need in one query, no matter how many entities we are pulling back.
Subselects can be used in conjunction with relationships to provide a dynamic, constrained relationship. In this example we will pull the latest post for a user.
This can be executed as follows:
As you can see, we are loading the id of the latest post in a subquery and then using that value to eager load the latestPost
relationship. This sequence will only execute two queries, no matter how many records are loaded.
Last updated