Filament Date Scopes Filter Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require aymanalhattami/filament-date-scopes-filter laracraft/date-scopes
   

   Ensure your models use Laracraft\DateScopes\HasDateScopes trait and define dateScopes() in the model.

2. Publish Config (Optional)

   php artisan vendor:publish --provider="AymanAlhattami\FilamentDateScopesFilter\FilamentDateScopesFilterServiceProvider"
   

   Customize default scopes or UI labels in config/filament-date-scopes-filter.php.

3. First Use Case Add the filter to a Filament table:

   use AymanAlhattami\FilamentDateScopesFilter\Filters\DateScopesFilter;
   
   public function table(Table $table): Table
   {
       return $table
           ->columns([...])
           ->filters([
               DateScopesFilter::make('date_scopes')
                   ->label('Time Period')
                   ->query($this->query) // Optional: Override default query
           ]);
   }
   

Implementation Patterns

Core Workflows

1. Basic Filtering Use the default scope configuration for common time periods (e.g., "Last 7 Days", "This Month").

   DateScopesFilter::make('date_scopes')
       ->label('Custom Label')
   

2. Custom Scopes Extend default scopes via model’s dateScopes() method:

   // In your model
   public function dateScopes(): array
   {
       return [
           'custom_scope' => [
               'label' => 'Custom Period',
               ->query(fn (Builder $query) => $query->where(...)),
           ],
       ];
   }
   

3. Dynamic Query Binding Bind the filter to a specific query (e.g., for relationships):

   DateScopesFilter::make('date_scopes')
       ->query(Order::query()->where('status', 'completed'))
   

4. Multi-Column Filtering Filter across multiple date columns:

   DateScopesFilter::make('date_scopes')
       ->columns(['created_at', 'updated_at'])
   

5. Integration with Existing Filters Combine with other Filament filters (e.g., SelectFilter):

   ->filters([
       DateScopesFilter::make('date_scopes'),
       SelectFilter::make('status')->options([...]),
   ])
   

Gotchas and Tips

Common Pitfalls

1. Missing HasDateScopes Trait Ensure your model uses use Laracraft\DateScopes\HasDateScopes; and defines dateScopes(). Fix: Add the trait and method to your model.

2. Query Scope Conflicts If using custom scopes, ensure they don’t conflict with existing query scopes (e.g., global scopes). Fix: Use ->withoutGlobalScopes() or adjust scope logic.

3. Performance with Large Datasets Complex date scopes (e.g., "Last 10 Years") may slow queries. Tip: Add database indexes to filtered columns or limit scope granularity.

4. Localization Issues Scope labels may not translate if not configured. Fix: Publish the config and override labels:

   'labels' => [
       'seconds' => __('Custom.Seconds'),
   ],
   

Debugging Tips

• Check Scope Application Use dd($this->query->toSql()) in a resource’s getTableQuery() to verify applied scopes.
• Log Filter Inputs Add a ->logFn(fn ($record) => Log::debug($record)) to debug filtered records.

Extension Points

1. Custom UI Components Override the default dropdown via a Filament widget:

   DateScopesFilter::make('date_scopes')
       ->widget(fn () => CustomDateScopeWidget::make())
   

2. Dynamic Scope Options Fetch scopes from an API or database:

   ->options(fn () => Scope::query()->pluck('label', 'key'))
   

3. Preset Default Scope Set a default scope (e.g., "This Month"):

   ->default('this_month')
   

4. Exclude Scopes Hide specific scopes:

   ->excludeScopes(['decades', 'millenniums'])