Query scopes in Eloquent help organize and reuse query logic by defining custom methods on models. 1. Local scopes are defined with a scope prefix and apply reusable constraints, like filtering popular users via scopePopular(). 2. They can accept parameters, such as scopeWithMinFollowers() for dynamic filtering. 3. Scopes should be used to avoid repetitive where clauses, streamline controllers, and model-level filters like active() or published(). 4. They work only on query builders, not collections, and should have clear, descriptive names. 5. Combine scopes with conditionals for flexible dynamic queries, improving maintainability and testability across applications like APIs or admin panels.

When you're working with Eloquent in Laravel and find yourself repeating the same types of query constraints across different parts of your app, query scopes are a great way to keep your code clean and reusable. They let you define common query logic inside your model so you can reuse it anywhere without duplicating code.

What Are Query Scopes?

In simple terms, query scopes are custom methods you define on your Eloquent models that apply certain query constraints. These can be used to filter results based on specific conditions every time you need them.

There are two types:

• Local Scopes: These start with scope and allow you to add reusable query constraints.
• Global Scopes: These automatically apply to all queries for a model — useful for things like soft-deleting or tenant-based filtering.

We'll focus mainly on local scopes here since they're more commonly used by developers in day-to-day work.

How to Define a Local Scope

Let's say you often want to get "popular" users — maybe those with more than 100 followers. Instead of writing this condition manually each time, you can define a scope:

// In your User model
public function scopePopular($query)
{
    return $query->where('followers', '>', 100);
}

Then, when querying, you just do:

$users = User::popular()->get();

It’s important to note that the method must start with scope, and the first parameter should always be the $query. This tells Eloquent it's a scope.

You can also chain scopes together:

$users = User::popular()->active()->orderBy('name')->get();

If your scope needs parameters, like filtering by a minimum number of followers, you can do that too:

public function scopeWithMinFollowers($query, $min)
{
    return $query->where('followers', '>', $min);
}

And call it like:

User::withMinFollowers(50)->get();

When Should You Use Scopes?

Use scopes when:

• You’re writing the same where clauses in multiple places.
• You want to make your controllers thinner and push logic into the model layer.
• You have filters that are meaningful at the model level (like active(), published(), recent()).

They help avoid messy controller methods and make your code easier to test and maintain.

Some real-world examples include:

• Filtering out inactive users
• Getting posts published in the last week
• Returning only verified accounts

Also, if you're building an API or admin panel with lots of filters, scopes can help you cleanly build dynamic queries.

A Few Things to Watch Out For

• Scopes only work on the query builder — not on collections. So don’t try to use them after calling get() or looping through results.
• Make sure your naming is clear. A scope called active() should clearly indicate what it does — ideally without needing extra comments.
• If you're using complex logic, consider combining scopes with query builder conditionals for flexibility.

For example:

$query = User::query();

if ($request->has('only_popular')) {
    $query->popular();
}

$users = $query->get();

This keeps your logic flexible and easy to extend later.

That's basically how query scopes work in Eloquent. It's not complicated, but it’s super useful once you start organizing your queries this way.

The above is the detailed content of How do I use query scopes in Eloquent?. For more information, please follow other related articles on the PHP Chinese website!