Imagine you have models for
Post and a relationship between the two —
Blog hasMany Post.
Post has a
datetime field called
published_at — but your posts aren’t necessarily in order of date published, as some of them take longer to proof than others.
Across your site, you need to show the 3 most recently-published posts for each blog. Eloquent makes this easy:
But this quickly gets repetitive — and most examples are more complicated. Moreover, your logic for how recent is defined (is it on published date or created date?) is now all over the place.
Maybe we could define this once…
Writing a model scope
Post model, add the following function:
public function scopeRecent($query)
It’s also an example of a magic method — any function you create with a name in the format
scopeSomething becomes a scope you can apply.
You can now replace your code above with the scope:
You can also amend your scope to take parameters — Laravel calls these dynamic scopes:
public function scopeRecent($query, $count)
And this can be used by passing a value into your scope, such as
Some extra notes
Why is it sometimes orderBy and sometimes sortBy?
Inside the scope, you are querying the data as it gets fetched from the database — so you need to use Eloquent functions.
Outside the scope, you already have a collection of model instances so you need to use Collection functions.
If you can use Eloquent functions, they’ll be quicker because they are applied before the data is fetched from the database. When using collections, the full set of data is fetched before being filtered.
Telling your editor/IDE about magic methods
Because your scope is a magic method, your editor won’t be aware of the property it enables so you won’t get autocomplete or any of the other benefits your IDE should bring.
You can fix this by adding a special comment above the
class declaration. For example, if your scope function is
* @method mixed recent() Fetches recent items
mixed refers to the return type of the method, which depends on what your scope does — it’s likely to be a
Collection, but could be a single item.