Filament Value Range Filter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tapp/filament-value-range-filter:"^2.0"
   

   Ensure your filament/filament package is on v4.x/5.x for compatibility.

2. First Use Case: Add the filter to a Filament table column definition:

   use Tapp\FilamentValueRangeFilter\Column\ValueRangeFilterColumn;
   
   ValueRangeFilterColumn::make('price')
       ->min(0)
       ->max(1000)
       ->step(10)
   

   Place this in your Table class under columns() or filters().

3. Where to Look First:

   • Package Docs (check 2.x branch).
   • src/Column/ValueRangeFilterColumn.php for core logic.
   • Published translations (if needed) via php artisan vendor:publish --tag="filament-value-range-filter-translations".

Implementation Patterns

Basic Integration

1. Column Filtering: Attach to numeric columns (e.g., price, quantity, age) for range-based filtering:

   use Filament\Tables\Columns\SumColumn;
   
   SumColumn::make('total')
       ->numeric()
       ->prefix('$')
       ->valueRangeFilter() // Auto-applies default range
   

2. Custom Ranges: Define dynamic min/max via closures:

   ValueRangeFilterColumn::make('revenue')
       ->min(fn () => Model::min('revenue'))
       ->max(fn () => Model::max('revenue'))
   

3. Workflow Integration:

   • Table Filters: Group with other filters in getFilters():

     public static function getFilters(): array
     {
         return [
             ValueRangeFilterColumn::make('created_at')
                 ->label('Date Range')
                 ->min(fn () => now()->subYear())
                 ->max(fn () => now()),
             // Other filters...
         ];
     }
     

   • Form Fields: Use in Filament forms for input validation:

     use Tapp\FilamentValueRangeFilter\Forms\Components\ValueRange;
     
     ValueRange::make('budget')
         ->required()
         ->min(100)
         ->max(10000)
     

4. Query Builder: The package automatically binds to Eloquent queries. Override behavior via modifyQueryUsing():

   ValueRangeFilterColumn::make('weight')
       ->modifyQueryUsing(fn (Builder $query, $min, $max) => $query
           ->whereBetween('weight', [$min, $max])
           ->orWhereNull('weight'))
   

Gotchas and Tips

Common Pitfalls

1. Non-Numeric Columns:

   • Error: Throws InvalidArgumentException if applied to non-numeric columns (e.g., strings, booleans).
   • Fix: Use ->numeric() on the column or wrap in a SumColumn/IntegerColumn.

2. Dynamic Ranges:

   • Gotcha: Closures in min()/max() are called per request, not cached. For performance, precompute values:

     ->min(fn () => Cache::remember('min_price', now()->addHours(1), fn () => Model::min('price')))
     

3. Step Attribute:

   • Quirk: step() affects UI granularity but does not enforce query precision. Use ->modifyQueryUsing() to adjust SQL:

     ->step(0.5)
     ->modifyQueryUsing(fn ($query, $min, $max) => $query
         ->where('price', '>=', $min)
         ->where('price', '<=', ceil($max)))
     

4. Translation Keys:

   • Tip: Publish translations if using custom labels:

     php artisan vendor:publish --tag="filament-value-range-filter-translations"
     

   • Override via getLabel() or configureUsing():

     ->configureUsing(fn (ValueRangeFilter $component) => $component
         ->label(__('custom.range_label')))
     

Debugging

1. Query Inspection: Use Laravel’s query logging to verify range binding:

   DB::enableQueryLog();
   $table->getRecords(); // Trigger query
   dd(DB::getQueryLog());
   

2. Component Rendering: Check if the filter renders by inspecting the DOM or enabling Filament’s debug mode:

   Filament::serving(function () {
       \Filament\Support\Facades\FilamentAsset::register();
       \Filament\Support\Facades\FilamentAsset::registerScripts();
   });
   

Extension Points

1. Custom UI: Extend the Vue component (resources/js/components/ValueRangeFilter.vue) to add features like:

   • Preset ranges (e.g., "Last 30 Days").
   • Custom icons or styling.

2. Validation: Combine with Filament’s validation rules:

   ValueRange::make('salary')
       ->rules([
           'min:value' => 30000,
           'max:value' => 200000,
       ])
   

3. Localization: Override translations in config/filament-value-range-filter.php:

   'labels' => [
       'min' => __('custom.min_value'),
       'max' => __('custom.max_value'),
   ],
   

4. Testing: Test range filters in PHPUnit:

   public function test_range_filter()
   {
       $this->actingAs($user)
            ->get('/admin/resource?min=100&max=500')
            ->assertSee('Filtered by price range');
   }