Filament Timezone Field Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require omar-haris/filament-timezone-field
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="OmarHaris\FilamentTimezoneField\FilamentTimezoneFieldServiceProvider"
   

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

   use OmarHaris\FilamentTimezoneField\Fields\Timezone;
   
   Timezone::make('timezone')
       ->label('User Timezone')
       ->required(),
   

3. Where to Look First

   • README.md for basic usage.
   • Changelog for breaking changes.
   • Source Code for customization hooks.

Implementation Patterns

Common Workflows

1. Basic Integration Use in Filament forms/resources:

   Timezone::make('timezone')
       ->default('America/New_York')
       ->rules(['required', 'timezone'])
       ->columnSpanFull(),
   

2. Localized Timezones Support multiple languages via config:

   // config/filament-timezone-field.php
   'languages' => [
       'en' => 'English',
       'es' => 'Español',
   ],
   

3. Dynamic Defaults Set defaults based on user location:

   Timezone::make('timezone')
       ->default(fn () => $this->getUserTimezone()),
   

4. Validation & Rules Combine with Laravel validation:

   Timezone::make('timezone')
       ->rules(['timezone', 'different:UTC'])
       ->helperText('Must be a valid timezone.'),
   

5. Custom Grouping Override region grouping (e.g., by continent):

   Timezone::make('timezone')
       ->groupBy('continent')
       ->groupLabels([
           'NA' => 'North America',
           'EU' => 'Europe',
       ]),
   

6. Livewire Integration Use in Livewire components:

   use OmarHaris\FilamentTimezoneField\Fields\Timezone;
   
   public function form(Form $form): void
   {
       $form->components([
           Timezone::make('timezone')->required(),
       ]);
   }
   

Pro Tips

• Performance: Cache timezone data if used frequently:

  Timezone::make('timezone')->cacheTimezones(true);
  

• Theming: Customize via Tailwind:

  Timezone::make('timezone')
      ->classes(['custom-class'])
      ->extraAttributes(['data-testid' => 'timezone-field']),
  

Gotchas and Tips

Pitfalls

1. Timezone Database Sync

   • The package uses PHP’s built-in timezone data. Ensure your server’s timezone database is up-to-date:

     sudo apt-get install tzdata  # Linux
     

   • Debugging: If timezones appear outdated, regenerate the cache:

     composer dump-autoload
     

2. Language Fallback

   • If a language isn’t supported, the field defaults to English. Explicitly set a fallback:

     Timezone::make('timezone')->language('en');
     

3. Filament Version Compatibility

   • Tested with Filament v2+. For v1, use an older package version or fork.
   • Error: Class 'Filament\Forms\Components\Select' not found → Ensure Filament is installed.

4. Database Storage

   • Timezones are stored as strings (e.g., America/New_York). Validate on retrieval:

     $timezone = Timezone::make('timezone')->getState();
     if (!in_array($timezone, Timezone::getAllTimezones())) {
         throw new \InvalidArgumentException("Invalid timezone: {$timezone}");
     }
     

5. Nested Forms

   • Timezone fields in nested forms may require explicit binding:

     Timezone::make('timezone')
         ->bindTo('user.timezone') // For nested models
         ->unboundValue(null),
     

Debugging Tips

• Log Timezone Data:

  \Log::info('Available timezones:', Timezone::getAllTimezones());
  

• Check Config:

  php artisan config:clear
  

  Then verify config/filament-timezone-field.php.

• Override Defaults: If the default timezone list is missing entries, extend the provider:

  // app/Providers/AppServiceProvider.php
  use OmarHaris\FilamentTimezoneField\TimezoneServiceProvider;
  
  public function boot()
  {
      TimezoneServiceProvider::macro('extendTimezones', function (array $customTimezones) {
          $this->timezones = array_merge($this->timezones, $customTimezones);
      });
  }
  

Extension Points

1. Custom Timezone Sources Replace the default timezone data source by binding a custom provider:

   // config/filament-timezone-field.php
   'timezone_provider' => \App\Services\CustomTimezoneProvider::class,
   

2. Event Listeners Listen for timezone changes in Filament:

   use OmarHaris\FilamentTimezoneField\Events\TimezoneChanged;
   
   TimezoneChanged::listen(function ($model, $timezone) {
       \Log::info("Timezone updated to {$timezone} for {$model->id}");
   });
   

3. API Responses Normalize timezones in API responses:

   // app/Http/Resources/UserResource.php
   public function toArray($request)
   {
       return [
           'timezone' => Timezone::normalize($this->timezone),
       ];
   }
   

4. Testing Mock timezone fields in tests:

   $this->filament->actingAs($user)
       ->modifyFormDataUsing(function (array $data) {
           $data['timezone'] = 'Europe/London';
           return $data;
       });