Filterable Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require heroicpixels/filterable
   

   Register the service provider in config/app.php:

   'providers' => [
       // ...
       Heroicpixels\Filterable\FilterableServiceProvider::class,
   ],
   

2. First Use Case: Apply the trait to an Eloquent model (e.g., User.php):

   use Heroicpixels\Filterable\FilterableTrait;
   
   class User extends Model
   {
       use FilterableTrait;
   
       protected $filterable = ['name', 'email', 'status'];
   }
   

   Now, a request to /users?name=John will automatically filter results where name = 'John'.

Where to Look First

• Model Configuration: Check $filterable array in your model to define which columns can be filtered.
• Request Handling: The package automatically parses Request query parameters, so no manual parsing is needed.
• Default Operators: Uses = by default for equality checks (e.g., ?status=active).

Implementation Patterns

Core Workflow

1. Define Filterable Columns:

   protected $filterable = ['column1', 'column2', 'status'];
   

   • Only these columns will accept query-based filtering.

2. Query Integration:

   $users = User::filterable()->get(); // Applies URL filters
   

   • Automatically appends WHERE clauses based on query params (e.g., ?status=active).

3. Customizing Behavior:

   • Operators: Override default operators in $filterable:

     protected $filterable = [
         'status' => ['operator' => 'like'],
         'created_at' => ['operator' => '>'],
     ];
     

   • Multiple Values: Use ?status[]=active&status[]=pending for IN clauses.

4. Wrapper Class: For non-Eloquent queries, use FilterableWrapper:

   $results = (new FilterableWrapper(User::query()))
       ->filterable()
       ->get();
   

Integration Tips

• APIs: Pair with Laravel’s Route::middleware('throttle') for filtered endpoints (e.g., /api/users?status=active).
• Admin Panels: Use in Laravel Nova or Filament for dynamic table filtering.
• Caching: Combine with Cache::remember to cache filtered results:

  Cache::remember("users_{$request->query()}", now()->addHours(1), function () {
      return User::filterable()->get();
  });
  

• Testing: Mock Request in tests:

  $request = Request::create('/users', 'GET', ['status' => 'active']);
  $this->app->instance('request', $request);
  

Gotchas and Tips

Pitfalls

1. SQL Injection:

   • The package escapes inputs, but never use raw user input for operators (e.g., ?status[operator]=DROP TABLE). Validate operators in $filterable:

     protected $filterable = [
         'status' => ['operator' => 'in'], // Explicitly restrict
     ];
     

2. Case Sensitivity:

   • Defaults to case-sensitive comparisons. For case-insensitive:

     protected $filterable = [
         'name' => ['operator' => 'like', 'modifier' => 'LOWER'],
     ];
     

3. Boolean Fields:

   • Use 1/0 or true/false in queries (e.g., ?is_active=1). Avoid ?is_active=true unless configured.

4. Performance:

   • Avoid filtering on non-indexed columns or large datasets. Use ->select() to limit columns:

     User::filterable()->select('id', 'name')->get();
     

Debugging

1. Log Queries: Enable Laravel’s query logging in .env:

   DB_LOG_QUERIES=true
   

   Check storage/logs/laravel.log for generated SQL.

2. Validate Filters:

   • Temporarily add dd($this->getFilterableQuery()) to your model’s filterable() method to inspect parsed filters.

3. Operator Mismatches:

   • If filters fail silently, verify operators in $filterable match the query (e.g., ?price__gt=100 requires operator: '>').

Extension Points

1. Custom Operators: Extend Heroicpixels\Filterable\Operators\OperatorResolver to add custom logic (e.g., contains for partial matches).

2. Pre-Filter Hooks: Override getFilterableQuery() in your model to modify filters before execution:

   protected function getFilterableQuery()
   {
       $query = parent::getFilterableQuery();
       $query->where('deleted_at', null); // Add soft-deletes
       return $query;
   }
   

3. Non-Standard Requests: For API tokens or non-Request inputs, bind the package’s Filterable class manually:

   $filterable = app('filterable');
   $filterable->setRequest($customRequest);
   

4. Localization: Override operator symbols for non-English apps (e.g., > → > in Spanish, but ensure consistency in $filterable).