Laravel Local Class Scope

A tiny macro that reuse a global scope class as a local scope.

The idea is from: [Proposal] Local query scopes as classes · Issue #636 · laravel/ideas

Requirements

• PHP: ^8.2
• Laravel: ^11.0 || ^12.0 || ^13.0 || ^14.0

[!NOTE] Older versions have outdated dependency requirements. If you cannot prepare the latest environment, please refer to past releases.

Installing

composer require mpyw/laravel-local-class-scope

Usage

Simple Scope

class ActiveScope implements Scope
{
    public function apply(Builder $query, Model $model): void
    {
        $query->where('active', true);
    }
}

User::scoped(ActiveScope::class)->get();

User::scoped(new ActiveScope())->get();

Scope that takes arguments

class AgeScope implements Scope
{
    protected $parameters;

    public function __construct(...$parameters)
    {
        $this->parameters = $parameters;
    }

    public function apply(Builder $query, Model $model): void
    {
        $query->where('age', ...$this->parameters);
    }
}

User::scoped(AgeScope::class, '>', 18)->get();

User::scoped(new AgeScope('>', 18))->get();

Combination

User::scoped(ActiveScope::class)->scoped(AgeScope::class, '>', 18)->get();

Re-define as a local method scope

class User extends Model
{
    public function scopeActive(Builder $query): Builder
    {
        return $this->scoped(ActiveScope::class);
    }
}

Share local method re-definition via trait

trait ScopesActive
{
    public function scopeActive(Builder $query): Builder
    {
        return $this->scoped(ActiveScope::class);
    }    
}

class User extends Model
{
    use ScopesActive;
}

class Admin extends Model
{
    use ScopesActive;
}

PHPStan extension

You can use the PHPStan extension to get better static analysis support for the scoped method.

To enable the extension, you need to include it in the phpstan.neon configuration file as follows:

includes:
    - vendor/mpyw/laravel-local-class-scope/extension.neon
    - vendor/larastan/larastan/extension.neon

[!IMPORTANT] If you are using Larastan (as is typical), you must include the extension of this package before Larastan's extension.