Filament Timezone Field Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   Ensure compatibility with your Filament version (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'),
       ]);
   }
   

3. Key Files to Review:

   • src/Forms/Components/TimezoneSelect.php (core logic)
   • src/Tables/Columns/TimezoneColumn.php (table display)
   • src/Tables/Filters/TimezoneSelectFilter.php (filtering)

Implementation Patterns

Common Workflows

1. User Profile Timezone Selection

TimezoneSelect::make('timezone')
    ->label('Preferred Timezone')
    ->getTimezoneFromBrowser() // Auto-populate from browser
    ->required()
    ->searchable()
    ->language('en'); // ISO 639-1 code

2. Regional Restriction (e.g., US/EU Only)

TimezoneSelect::make('timezone')
    ->byCountry(['US', 'GB', 'DE'])
    ->hideOffset(); // Show only timezone names

3. Table Column with Offset

TimezoneColumn::make('timezone')
    ->formattedOffsetAndTimezone()
    ->sortable();

4. Filtering by Timezone

TimezoneSelectFilter::make('timezone')
    ->label('Filter by Timezone')
    ->byRegion([Region::Europe, Region::Asia]);

5. Dynamic Language Based on User Locale

TimezoneSelect::make('timezone')
    ->language(auth()->user()->locale ?? 'en');

Integration Tips

Database Storage

• Store timezones as strings (e.g., 'America/New_York').
• Use Laravel’s Carbon for timezone-aware operations:

  $user->timezone = 'Europe/London';
  $localTime = Carbon::now($user->timezone);
  

Validation

Leverage Filament’s built-in validation:

TimezoneSelect::make('timezone')
    ->rules(['required', 'timezone']);

API Responses

Normalize timezone data in API resources:

public function toArray($request)
{
    return [
        'timezone' => $this->timezone,
        'timezone_offset' => $this->timezone ? (new DateTimeZone($this->timezone))->getOffset(new DateTime()) : null,
    ];
}

Multi-Language Support

Combine with Laravel’s localization:

TimezoneSelect::make('timezone')
    ->language(app()->getLocale());

Gotchas and Tips

Pitfalls

1. Browser Timezone Auto-Population:

   • getTimezoneFromBrowser() may fail on SPA/auth pages (fixed in v3.0.13).
   • Workaround: Use a fallback default:

     ->getTimezoneFromBrowser()
     ->default('UTC');
     

2. Empty Values in Tables:

   • Always handle null values in TimezoneColumn to avoid exceptions:

     TimezoneColumn::make('timezone')
         ->formatStateUsing(fn ($state) => $state ?? 'N/A');
     

3. Performance with Large Datasets:

   • Filtering by timezone in tables can be slow. Optimize with database indexes:

     $table->string('timezone')->index();
     

4. Timezone Database Updates:

   • The package uses PHP’s DateTimeZone, which relies on system libraries. Ensure your server’s timezone database is up-to-date.

Debugging Tips

1. Check Available Timezones:

   $timezones = DateTimeZone::listIdentifiers();
   dd($timezones); // Debug all available timezones
   

2. Log Filtered Timezones:

   TimezoneSelect::make('timezone')
       ->byCountry('US')
       ->afterStateUpdated(fn ($state) => Log::debug('Selected timezone:', [$state]));
   

3. Validate Timezone Strings:

   use DateTimeZone;
   $isValid = in_array($timezone, DateTimeZone::listIdentifiers());
   

Extension Points

1. Custom Timezone Groups: Extend the Region enum or create a custom filter:

   TimezoneSelect::make('timezone')
       ->byRegion(fn () => [Region::Europe, Region::Asia]) // Custom logic
       ->optionGrouping('Europe', fn () => collect([...]));
   

2. Override Default Options: Use modifyQueryUsing() to filter timezones dynamically:

   TimezoneSelect::make('timezone')
       ->modifyQueryUsing(fn (Builder $query) => $query->where(...));
   

3. Add Custom Metadata: Attach additional data to timezone options:

   TimezoneSelect::make('timezone')
       ->options([
           'America/New_York' => [
               'label' => 'New York (EDT)',
               'offset' => -4,
           ],
       ]);
   

4. Localization Hooks: Override labels/placeholders via Filament’s translation system:

   // resources/lang/en/forms.php
   'timezone_select' => [
       'label' => 'Select your timezone',
       'placeholder' => 'Choose a timezone...',
   ];
   

Configuration Quirks

1. Symfony Intl Dependency:

   • Required for language support. Ensure symfony/intl is installed:

     composer require symfony/intl
     

2. GMT vs. UTC:

   • Defaults to UTC. Use timezoneType('GMT') for GMT offsets:

     TimezoneSelect::make('timezone')
         ->timezoneType('GMT');
     

3. Legacy Filament Versions:

   • For Filament 2.x, use the 2.x branch. Features may differ.

4. Caching Timezone Data:

   • The package loads timezone data on initialization. For large apps, consider caching:

     Cache::remember('filament_timezones', now()->addHours(1), fn () => DateTimeZone::listIdentifiers());