Scopes Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require splash/scopes
   

   Add the service provider to config/app.php:

   Splash\Scopes\ScopesServiceProvider::class,
   

2. Basic Usage Define a scope in a model:

   use Splash\Scopes\Scope;
   
   class User extends Model
   {
       public function scopeActive($query)
       {
           return $query->where('active', true);
       }
   }
   

   Apply it in a query:

   $activeUsers = User::active()->get();
   

3. First Use Case

   • Filtering: Use scopes to encapsulate reusable query logic (e.g., scopePublished(), scopeArchived()).
   • API Endpoints: Apply scopes dynamically based on request parameters (e.g., User::scopeByRole($request->role)->get()).

Implementation Patterns

1. Dynamic Scopes

Use scope* methods for reusable filters:

// Model: User.php
public function scopeByRole($query, $role)
{
    return $query->where('role', $role);
}

// Usage:
User::byRole('admin')->get();

2. Conditional Scopes

Apply scopes conditionally (e.g., based on auth or request):

public function scopeForAdmin($query)
{
    if (auth()->check()) {
        return $query->where('admin', true);
    }
    return $query;
}

3. Global Scopes

For always-applied filters (e.g., soft deletes):

use Illuminate\Database\Eloquent\Scope;

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

// Register in model's boot():
protected static function boot()
{
    static::addGlobalScope(new ActiveScope);
}

4. Query Builder Integration

Extend QueryBuilder for non-model queries:

use Splash\Scopes\QueryBuilder;

$query = QueryBuilder::for(User::class)
    ->scope('active')
    ->scope('byRole', 'admin')
    ->get();

5. API Resource Filtering

Use scopes in API responses (e.g., ?filter=active):

// Route:
Route::get('/users', function () {
    return User::when(request('filter') === 'active', fn($q) => $q->active())
               ->get();
});

Gotchas and Tips

Pitfalls

1. Naming Conflicts Avoid naming scopes like scopeWhere* (reserved for Laravel’s dynamic scopes). Stick to scope* or scopeBy*.

2. Global Scope Overhead Global scopes run on every query. Use sparingly—profile with DB::enableQueryLog().

3. Caching Issues Scopes bypass Laravel’s query cache. Cache results manually if needed:

   $users = Cache::remember('active_users', now()->addHour(), fn() => User::active()->get());
   

Debugging

• Log Queries Enable Laravel’s query logging:

  DB::enableQueryLog();
  User::active()->get();
  dd(DB::getQueryLog());
  

• Scope Isolation If scopes interfere, chain them explicitly:

  // Bad: Assumes order
  User::active()->byRole('admin');
  
  // Good: Explicit
  User::byRole('admin')->active();
  

Extension Points

1. Custom Scope Logic Extend Splash\Scopes\Scope for complex behavior (e.g., multi-table joins).

2. Request-Based Scopes Use middleware to attach scopes dynamically:

   // Middleware: ApplyUserScopes.php
   public function handle($request, Closure $next)
   {
       User::addGlobalScope(new RequestScope($request));
       return $next($request);
   }
   

3. Testing Mock scopes in tests:

   $scope = $this->partialMockFor(User::class, ['scopeActive']);
   $scope->scopeActive()->willReturn($query);
   

Performance Tips

• Eager Load Dependencies Scopes may trigger N+1 queries. Use with():

  User::active()->with('posts')->get();
  

• Indexed Columns Ensure scoped columns (e.g., active) are indexed for large datasets.