Filament Daterangepicker Filter Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require malzariey/filament-daterangepicker-filter
   

   Publish translations if needed:

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

2. First Use Case: Add the field to a Filament form or resource:

   use Malzariey\FilamentDaterangepickerFilter\Fields\DateRangePicker;
   
   DateRangePicker::make('created_at')
       ->label('Date Range')
       ->required();
   

3. As a Filter:

   use Malzariey\FilamentDaterangepickerFilter\Filters\DateRangeFilter;
   
   DateRangeFilter::make('created_at')
       ->label('Filter by Date')
       ->placeholder('Select a date range');
   

Where to Look First

• Documentation: Focus on the README for basic usage and configuration.
• Demo: Check the Filament Demo for visual examples.
• Source: Explore the Fields and Filters directories for customization.

Implementation Patterns

Common Workflows

1. Basic Date Range Picker

DateRangePicker::make('event_date')
    ->label('Event Duration')
    ->required()
    ->format('d/m/Y');

2. Month-Level Filtering

DateRangeFilter::make('billing_period')
    ->monthPicker()
    ->label('Billing Month')
    ->format('F Y')
    ->modifyQueryUsing(fn(Builder $query, ?Carbon $startDate, ?Carbon $endDate) =>
        $query->whereBetween('billing_date', [$startDate, $endDate])
    );

3. Year-Level Selection

DateRangePicker::make('fiscal_year')
    ->yearPicker()
    ->label('Fiscal Year')
    ->format('Y')
    ->minYear(2020)
    ->maxYear(2030);

4. Time-Inclusive Picker

DateRangePicker::make('shift_time')
    ->timePicker()
    ->timePicker24()
    ->timePickerIncrement(30)
    ->format('d/m/Y H:i');

5. Keyboard Input with Validation

DateRangePicker::make('custom_date')
    ->allowInput()
    ->format('d/m/Y')
    ->placeholder('Type a date (e.g., 15/06/2024)');

Integration Tips

Livewire Integration

• Dual State Mode: Store start/end dates separately:

  DateRangePicker::make('date_range')
      ->useDualState('start_date', 'end_date');
  

  In your Livewire component:

  public ?string $start_date = null;
  public ?string $end_date = null;
  

• Custom Events: Listen for changes via JavaScript:

  document.addEventListener('apply.daterangepicker', (e) => {
      console.log('Selected:', e.detail.startDate, e.detail.endDate);
      // Update Livewire properties or trigger actions
  });
  

Query Modification

• Override default whereBetween logic:

  DateRangeFilter::make('created_at')
      ->modifyQueryUsing(fn(Builder $query, ?Carbon $startDate, ?Carbon $endDate) =>
          $query->where('created_at', '>=', $startDate)
               ->where('created_at', '<=', $endDate)
      );
  

Presets and Defaults

• Predefined ranges for common filters:

  DateRangePicker::make('created_at')
      ->ranges([
          'Today' => [now(), now()],
          'This Week' => [now()->startOfWeek(), now()->endOfWeek()],
          'Last 30 Days' => [now()->subDays(30), now()],
      ])
      ->defaultToday();
  

Localization

• Publish translations and customize:

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

  Edit resources/lang/vendor/filament-daterangepicker-filter/xx.json.

Modal/Slide-Over Compatibility

• Ensure dropdowns render outside Filament’s z-index conflicts:

  DateRangePicker::make('dates')->teleport(); // Default: true
  

Gotchas and Tips

Pitfalls

1. Format Mismatches

• Issue: Using deprecated displayFormat() (e.g., 'DD/MM/YYYY') instead of format() with Carbon tokens.
• Fix: Replace with:

  ->format('d/m/Y') // Correct (auto-converts to JS)
  

2. Time Picker Conflicts

• Issue: Time picker options (e.g., timePicker24()) may not apply if called after timePicker().
• Fix: Chain methods in the correct order:

  ->timePicker()
      ->timePicker24()
      ->timePickerIncrement(30);
  

3. Year/Month Picker Constraints

• Issue: minYear()/maxYear() may not restrict month/year picker inputs as expected.
• Fix: Explicitly set minDate()/maxDate for stricter control:

  ->monthPicker()
      ->minDate('2020-01-01')
      ->maxDate('2030-12-31');
  

4. Dual State Mode Pitfalls

• Issue: Forgetting to define both $start_date and $end_date properties in Livewire.
• Fix: Always declare both properties:

  public ?string $start_date = null;
  public ?string $end_date = null;
  

5. Keyboard Input Validation

• Issue: Partial invalid input (e.g., typing 06/202 in m/Y format) may overwrite valid selections.
• Fix: Use allowInput() judiciously and validate server-side:

  ->allowInput()
      ->format('m/Y'); // Ensures strict validation
  

Debugging Tips

1. Console Logs for Events

• Listen for events to debug interactions:

  document.addEventListener('apply.daterangepicker', (e) => {
      console.log('Applied:', e.detail);
  });
  document.addEventListener('cancel.daterangepicker', (e) => {
      console.log('Cancelled:', e.detail);
  });
  

2. Check Alpine.js State

• Inspect the rendered HTML for Alpine.js x-data attributes to verify dynamic state:

  <input x-data="..." x-model="...">
  

3. Validate Date Parsing

• Ensure format() matches the expected input/output:

  ->format('Y-m-d H:i:s'); // ISO format for API consistency
  

4. Z-Index Conflicts

• If dropdowns are hidden behind other elements:

  ->teleport(true); // Force teleport to body (default)
  

Extension Points

1. Custom Presets

• Dynamically generate presets based on business logic:

  ->ranges(array_map(fn($year) => [
      "FY $year" => ["$year-01-01", "$year-12-31"]
  ], range(2020, 2030)));
  

2. Conditional Logic

• Show/hide fields based on other inputs:

  ->visible(fn() => $this->some_condition)
  

3. Custom Query Logic

• Extend modifyQueryUsing for complex filters:

  ->modifyQueryUsing(fn(Builder $query, ?Carbon $startDate, ?Carbon $endDate) =>
      $query->when($startDate, fn($q) => $q->where('date', '>=', $startDate))
           ->when($endDate, fn($q) => $q->where('date', '<=', $endDate))
  );
  

4. Localization Overrides

• Override specific translations:

  // In a service provider
  app()->setLocale('fr');
  

5. Styling Customization

• Extend Alpine.js data to modify UI:

  document.addEventListener('alpine:init', () => {
      Alpine.data('customDateRangePicker', () => ({
          init() {
              // Modify Alpine.js behavior
          }
      }));
  });