Filament Timezone Field Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tapp/filament-timezone-field:"^3.0"
   

   Ensure your filament/filament package is compatible (3.x/4.x/5.x).

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

   use Tapp\FilamentTimezoneField\Forms\Components\TimezoneSelect;
   
   public static function form(Form $form): Form
   {
       return $form->schema([
           TimezoneSelect::make('timezone'),
       ]);
   }
   

   This renders a dropdown with all timezones (default: UTC).

Where to Look First

• Documentation: README.md for quick start.
• Source: src/Forms/Components/TimezoneSelect.php for customization hooks.
• Changelog: Review v3.x for breaking changes (e.g., Filament 5 support in v3.0.12).

Implementation Patterns

Common Workflows

1. User-Specific Timezone Selection:

   TimezoneSelect::make('timezone')
       ->getTimezoneFromBrowser() // Auto-populate from browser (non-overriding)
       ->required();
   

2. Regional Filtering:

   use Tapp\FilamentTimezoneField\Enums\Region;
   
   TimezoneSelect::make('timezone')
       ->byRegion([Region::Europe, Region::Asia])
       ->searchable();
   

3. Table Integration:

   use Tapp\FilamentTimezoneField\Tables\Columns\TimezoneColumn;
   
   TimezoneColumn::make('timezone')
       ->formattedOffsetAndTimezone()
       ->timezoneType('GMT');
   

4. Filtering Records:

   use Tapp\FilamentTimezoneField\Tables\Filters\TimezoneSelectFilter;
   
   TimezoneSelectFilter::make('timezone')
       ->byCountry('US')
       ->language('es');
   

Integration Tips

• Validation: Use Filament’s built-in validation (e.g., ->rules(['required'])).
• Localization: Pass ISO 639-1 codes (e.g., ->language('fr')) for multilingual apps.
• Performance: Pre-filter timezones server-side if the list is large (e.g., via byCountry()).
• SPA/Auth Pages: Avoid getTimezoneFromBrowser() if users aren’t authenticated (fixed in v3.0.13).

Gotchas and Tips

Pitfalls

1. Browser Timezone Override:

   • getTimezoneFromBrowser() may fail on SPA/auth pages (fixed in v3.0.13). Test in production-like environments.
   • Workaround: Disable it or handle JS errors gracefully.

2. Empty Values in Columns:

   • Older versions (pre-v3.0.5) threw exceptions if timezone was null. Always ensure your model has a default or nullable field.

3. Symfony Intl Dependency:

   • Required for localization (added in v3.0.9). Ensure symfony/intl is installed:

     composer require symfony/intl
     

4. Region Enums:

   • Predefined Region enums (e.g., Region::Australia) may not cover all edge cases. Fall back to DateTimeZone constants if needed.

Debugging Tips

• Timezone Display Issues:

  • Check if the field value is a valid DateTimeZone instance. Use:

    $timezone = new DateTimeZone($record->timezone);
    

  • Log the raw value: dd($this->getState()) in a custom field extension.

• Performance:

  • If the dropdown is slow, lazy-load options by overriding getOptions() in a custom field class.

Extension Points

1. Custom Field Logic: Extend TimezoneSelect to add logic (e.g., dynamic country filtering):

   class CustomTimezoneSelect extends TimezoneSelect
   {
       public function getOptions(): array
       {
           return parent::getOptions()->filter(fn ($option) => str_contains($option['label'], 'Europe'));
       }
   }
   

2. Table Column Formatting: Override getFormattedValue() to customize display:

   TimezoneColumn::make('timezone')
       ->modifyQueryUsing(fn (Builder $query) => $query->whereNotNull('timezone'))
       ->formatStateUsing(fn ($state) => "Custom: $state");
   

3. Filter Logic: Extend TimezoneSelectFilter to add custom queries:

   class CustomTimezoneFilter extends TimezoneSelectFilter
   {
       protected function setUp(): void
       {
           parent::setUp();
           $this->query(fn (Builder $query) => $query->where('active', true));
       }
   }
   

Pro Tips

• Default Timezone: Set a default in your model’s $casts:

  protected $casts = [
      'timezone' => 'string',
  ];
  

  Or use default() on the field:

  TimezoneSelect::make('timezone')->default('America/New_York');
  

• Testing: Mock browser timezone in tests:

  $this->actingAs($user)->withHeaders(['X-Timezone' => 'Europe/London']);
  

• Accessibility: Combine with Filament’s ->label() and ->helperText() for clarity:

  TimezoneSelect::make('timezone')
      ->label('User Timezone')
      ->helperText('Select the timezone for scheduling.');