Laravel Filter Components Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require labrodev/laravel-filter-components
   

   Publish the package's views (optional, for customization):

   php artisan vendor:publish --provider="Labrodev\LaravelFilterComponents\LaravelFilterComponentsServiceProvider" --tag="views"
   

2. Basic Usage Register a filter in your controller or service:

   use Labrodev\LaravelFilterComponents\Filters\DateRangeFilter;
   use Labrodev\LaravelFilterComponents\Filters\IsNotNullFilter;
   use Labrodev\LaravelFilterComponents\Filters\WhereInFilter;
   
   $queryBuilder = new \Spatie\QueryBuilder\QueryBuilder($model);
   $queryBuilder->addFilter(new DateRangeFilter('created_at'));
   $queryBuilder->addFilter(new IsNotNullFilter('unpaid_invoices'));
   $queryBuilder->addFilter(new WhereInFilter('status', ['active', 'pending']));
   

3. First Use Case Render a filter form in your Blade view:

   @filterComponent('dateRange', 'created_at', 'Created At')
   @filterComponent('isNotNull', 'unpaid_invoices', 'Has Unpaid Invoices')
   @filterComponent('whereIn', 'status', 'Status', ['active', 'pending'])
   

Implementation Patterns

Usage Patterns

1. Filter Registration

   • Register filters in your QueryBuilder instance dynamically or statically:

     // Dynamic registration (e.g., in a controller)
     $queryBuilder = (new QueryBuilder($model))
         ->addFilter(new DateRangeFilter('date_column'))
         ->addFilter(new WhereInFilter('category', ['web', 'mobile']));
     

2. View Integration

   • Use Blade directives (@filterComponent) to render filters in your views:

     @filterComponent('dateRange', 'published_at', 'Publication Date')
     

   • Pass additional options (e.g., labels, placeholders):

     @filterComponent('whereIn', 'tags', 'Tags', ['web', 'laravel'], label: 'Select Tags')
     

3. Custom Filter Logic

   • Extend existing filters or create new ones by implementing the FilterInterface:

     use Labrodev\LaravelFilterComponents\Contracts\FilterInterface;
     
     class CustomFilter implements FilterInterface {
         public function apply($queryBuilder, $query, $value) {
             // Custom logic here
             return $query->where('custom_column', $value);
         }
     }
     

4. QueryBuilder Integration

   • Chain filters with Spatie’s QueryBuilder methods:

     $results = $queryBuilder
         ->allowedFilters(['dateRange', 'whereIn'])
         ->paginate();
     

Workflows

1. CRUD Filtering

   • Use filters in index actions to pre-filter results:

     public function index(Request $request) {
         $queryBuilder = (new QueryBuilder(Post::class))
             ->addFilter(new DateRangeFilter('created_at'))
             ->allowedFilters(['dateRange', 'whereIn']);
     
         return view('posts.index', [
             'posts' => $queryBuilder->paginate(),
         ]);
     }
     

2. Reusable Filter Groups

   • Group filters by feature (e.g., "Advanced Search"):

     $advancedFilters = [
         new WhereInFilter('status', ['draft', 'published']),
         new DateRangeFilter('updated_at'),
     ];
     $queryBuilder->addFilters($advancedFilters);
     

3. Dynamic Filter Loading

   • Load filters based on user roles or permissions:

     if (auth()->user()->isAdmin()) {
         $queryBuilder->addFilter(new WhereInFilter('user_id', User::all()->pluck('id')));
     }
     

Integration Tips

1. Form Request Validation

   • Validate filter inputs in FormRequest classes:

     public function rules() {
         return [
             'date_from' => 'sometimes|date',
             'date_to' => 'sometimes|date',
             'status' => 'sometimes|in:active,pending',
         ];
     }
     

2. URL Parameter Handling

   • Use QueryBuilder's built-in URL parameter handling:

     $queryBuilder->defaultSort('created_at', 'desc');
     

3. Localization

   • Override Blade views to support localization:

     @filterComponent('dateRange', 'created_at', __('Created At'))
     

4. Testing

   • Test filters in isolation:

     public function test_date_range_filter() {
         $query = Post::query();
         $filter = new DateRangeFilter('created_at');
         $filter->apply($query, $query, ['from' => '2023-01-01', 'to' => '2023-12-31']);
     
         $this->assertDatabaseHas('posts', [
             'created_at' => '2023-06-01',
         ]);
     }
     

Gotchas and Tips

Pitfalls

1. View Publishing

   • Forgetting to publish views may result in missing Blade directives:

     php artisan vendor:publish --tag="views"
     

2. Filter Overwriting

   • Adding duplicate filters can override previous logic. Use allowedFilters() to restrict:

     $queryBuilder->allowedFilters(['dateRange']); // Only allow dateRange
     

3. DateRangeFilter Quirks

   • Ensure date_from and date_to parameters are named correctly in requests:

     // Correct: date_from=2023-01-01&date_to=2023-12-31
     // Incorrect: from=2023-01-01&to=2023-12-31 (will fail silently)
     

4. WhereInFilter Edge Cases

   • Empty arrays or null values may cause SQL errors. Validate inputs:

     $values = $request->input('status') ?? [];
     if (!is_array($values)) $values = [$values];
     

5. IsNotNullFilter Logic

   • The filter assumes true/false or 1/0 for whereNotNull/whereNull. Customize if needed:

     $filter = new IsNotNullFilter('column', 'custom_true_value', 'custom_false_value');
     

Debugging

1. Query Inspection

   • Use toSql() and getBindings() to debug queries:

     dd($queryBuilder->getQuery()->toSql(), $queryBuilder->getQuery()->getBindings());
     

2. Filter Application Order

   • Filters are applied in registration order. Reorder if logic conflicts:

     $queryBuilder->addFilter(new WhereInFilter('status'))->addFilter(new DateRangeFilter('created_at'));
     

3. Blade Directive Errors

   • Check for typos in @filterComponent directives or missing views:

     php artisan view:clear
     

Tips

1. Custom Filter Styling

   • Override default views in resources/views/vendor/labrodev-filter-components:

     <!-- Example: Custom date range input -->
     <div class="custom-date-filter">
         {{ $input }}
     </div>
     

2. Performance

   • Use allowedFilters() to restrict filters and avoid unnecessary logic:

     $queryBuilder->allowedFilters(['dateRange']); // Only allow dateRange
     

3. Dynamic Filter Labels

   • Pass labels dynamically from the controller:

     return view('posts.index', [
         'filters' => [
             'dateRange' => __('Custom Date Label'),
         ],
     ]);
     

4. Filter Persistence

   • Use QueryBuilder's remember() to persist filters across sessions:

     $queryBuilder->remember();
     

5. Extending Filters

   • Create reusable filter classes for complex logic:

     class StatusFilter extends WhereInFilter {
         protected $defaultValues = ['active', 'pending', 'draft'];
         public function __construct($column) {
             parent::__construct($column, $this->defaultValues);
         }
     }
     

6. API Integration

   • Use filters in API endpoints with QueryBuilder's JSON response:

     return $queryBuilder->paginate()->withQueryString();