Filament Datefilter Laravel Package

Getting Started

Minimal Setup

1. Installation: Requires Filament ≥2.15. Add via Composer:

   composer require webbingbrasil/filament-datefilter
   

2. Publish Config (if needed):

   php artisan vendor:publish --provider="Webbingbrasil\FilamentDateFilter\FilamentDateFilterServiceProvider"
   

3. First Use Case: Add to a Filament table’s $filters property:

   use Webbingbrasil\FilamentDateFilter\DateFilter;
   
   public static function table(Table $table): Table
   {
       return $table
           ->filters([
               DateFilter::make('created_at')
                   ->label('Created At')
                   ->minDate(now()->subMonth())
                   ->maxDate(now()->addMonth()),
           ]);
   }
   

Key Files to Review

• Service Provider: config/filament-datefilter.php (if published) for global defaults.
• Filter Class: src/DateFilter.php for method reference.

Implementation Patterns

Common Workflows

1. Single Date Filter:

   DateFilter::make('published_at')
       ->label('Publication Date')
       ->defaultDate(now()->startOfMonth())
       ->timeZone('Europe/London');
   

   • Use defaultDate() to pre-select a value (e.g., current month).

2. Date Range Filter:

   DateFilter::make('order_date')
       ->label('Order Period')
       ->minDate(now()->subYear())
       ->maxDate(now())
       ->range()
       ->fromLabel('Start Date')
       ->untilLabel('End Date');
   

   • Pro Tip: Combine with ->required() to enforce selection.

3. Dynamic Column Mapping:

   DateFilter::make('custom_field')
       ->useColumn('actual_date_column')
       ->label('Custom Date');
   

   • Useful for legacy DB schemas or computed columns.

4. Integration with Filament Actions:

   public static function getTableFilters(): array
   {
       return [
           DateFilter::make('created_at')
               ->label('Filter by Date')
               ->range(),
           // Other filters...
       ];
   }
   

Advanced Patterns

• Conditional Date Ranges: Use Filament’s modifyQueryUsing() to adjust logic:

  DateFilter::make('event_date')
      ->range()
      ->modifyQueryUsing(fn (Builder $query, array $data) => $query
          ->whereBetween('event_date', [$data['from'], $data['until']])
          ->orWhereNull('event_date'));
  

• Custom Timezone Handling: Override the default timezone per filter:

  DateFilter::make('scheduled_at')
      ->timeZone('Asia/Tokyo');
  

Gotchas and Tips

Pitfalls

1. Timezone Mismatches:

   • Issue: Filters may return unexpected results if the DB timezone differs from the filter’s timezone.
   • Fix: Ensure timeZone() matches your DB’s timezone (e.g., UTC).
   • Debug: Use ->timeZone('UTC')->defaultDate(now('UTC')) for consistency.

2. Null Handling:

   • Issue: range() filters may not handle null values gracefully in queries.
   • Fix: Explicitly check for null in modifyQueryUsing:

     ->modifyQueryUsing(fn ($query, $data) => $query
         ->when($data['from'] ?? null, fn ($q) => $q->where('date', '>=', $data['from']))
         ->when($data['until'] ?? null, fn ($q) => $q->where('date', '<=', $data['until'])));
     

3. Archived Package:

   • Risk: No updates since 2022. Fork or replace if critical for production.
   • Mitigation: Check for forks (e.g., spatie/filament-date-filter) or maintain a local patch.

4. Performance:

   • Issue: Wide date ranges (e.g., minDate far in the past) can slow queries.
   • Fix: Limit ranges dynamically:

     ->minDate(now()->subDays(30)) // Recent 30 days only
     ->maxDate(now());
     

Debugging Tips

• Inspect Filter Data: Add a dd() in modifyQueryUsing to verify $data structure:

  ->modifyQueryUsing(fn ($query, $data) => {
      dd($data); // Check keys: 'from', 'until', or 'date' (single date)
      return $query->where(...);
  });
  

• Check Published Config: Override defaults in config/filament-datefilter.php:

  'default_timezone' => 'UTC',
  'range_labels' => [
      'from' => 'Start',
      'until' => 'End',
  ],
  

Extension Points

1. Custom UI Components: Extend the filter’s Blade view (resources/views/filament-datefilter/...) to add icons or tooltips.
2. Localization: Override labels globally via config or per-filter:

   ->fromLabel(__('Desde'))
   ->untilLabel(__('Hasta'));
   

3. Presets: Create reusable filter configurations in a trait:

   trait UsesDateFilters {
       protected function dateRangeFilter(string $column): DateFilter {
           return DateFilter::make($column)
               ->range()
               ->minDate(now()->subYear())
               ->maxDate(now());
       }
   }