Filament Timepicker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require husam-tariq/filament-timepicker
   

   No additional configuration is required unless you need to customize views.

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

   use HusamTariq\FilamentTimePicker\Forms\Components\TimePickerField;
   
   TimePickerField::make('event_time')
       ->label('Event Time')
       ->required(),
   

3. Where to Look First:

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

Implementation Patterns

Common Workflows

1. Basic Time Selection:

   TimePickerField::make('start_time')
       ->label('Start Time')
       ->default(now()->format('H:i:s')),
   

2. Time Range Selection (e.g., for appointments):

   $form->schema([
       TimePickerField::make('start_time')->label('Start Time'),
       TimePickerField::make('end_time')
           ->label('End Time')
           ->afterStateUpdated(fn ($state, callable $set) => $set('min', $state['start_time'])),
   ]);
   

3. Integration with Validation:

   TimePickerField::make('deadline')
       ->label('Deadline')
       ->rules(['after:now', 'before:23:59:59']),
   

4. Dynamic Time Constraints: Use afterStateUpdated or beforeStateHydrated to enforce logic:

   TimePickerField::make('end_time')
       ->afterStateUpdated(fn ($state, callable $set) => $set('min', now()->format('H:i:s')))
       ->afterStateUpdated(fn ($state, callable $set) => $set('max', '23:59:59')),
   

5. Customizing UI:

   • Override Blade views by publishing assets:

     php artisan vendor:publish --tag="filament-timepicker-views"
     

   • Extend with custom CSS/JS via Filament’s asset pipeline.

Integration Tips

• Filament Resources: Use in create() or edit() methods of Filament resources:

  public static function form(Form $form): Form
  {
      return $form
          ->schema([
              TimePickerField::make('time_slot')->required(),
          ]);
  }
  

• Livewire Components: Works seamlessly with Filament’s Livewire integration. No extra setup needed.

• Database Storage: The field stores time in H:i:s format by default. Ensure your database column matches:

  $table->time('time_slot')->nullable();
  

• Localization: Supports Filament’s localization system. Translate labels via filament.lang config.

Gotchas and Tips

Pitfalls

1. Timezone Handling:

   • The field uses the browser’s local time by default. If your app uses a different timezone (e.g., UTC), ensure consistency:

     TimePickerField::make('time')
         ->timezone('UTC') // Explicitly set timezone
         ->default(now('UTC')->format('H:i:s')),
     

   • Gotcha: Stored times may appear offset if not handled. Use Carbon for conversion:

     $time = Carbon::parse($record->time_slot)->timezone('America/New_York');
     

2. Validation Quirks:

   • Rules like after:now or before:yesterday may behave unexpectedly with time-only fields. Use explicit formats:

     ->rules(['after:'.now()->format('H:i:s')]),
     

3. View Publishing:

   • Publishing views (vendor:publish) is optional but required for customizations. Forgetting this may break UI changes.

4. Step Increment:

   • Default step is 1 minute. For coarser granularity (e.g., 15-minute increments), use:

     TimePickerField::make('time')->step(15),
     

Debugging Tips

1. Console Logs: Enable Filament’s debug mode to inspect field state:

   Filament::serving(function () {
       \Log::debug('TimePicker state:', ['state' => $record->time_slot]);
   });
   

2. State Hydration: If beforeStateHydrated isn’t working, ensure the field is properly bound to the model attribute:

   TimePickerField::make('time_slot')
       ->columnSpanFull()
       ->beforeStateHydrated(fn (set) => $set('time_slot', $record->time_slot ?? '00:00:00')),
   

3. Asset Conflicts: If the timepicker UI breaks, check for:

   • Duplicate jQuery/Alpine.js instances.
   • Conflicting CSS (e.g., !important overrides).

Extension Points

1. Custom Time Format: Override the default H:i:s format by extending the field:

   class CustomTimePickerField extends TimePickerField
   {
       protected string $format = 'h:i A';
   
       public static function make(string $name): static
       {
           return parent::make($name);
       }
   }
   

   Register it in AppServiceProvider:

   Filament::registerFormComponentAs('custom-time-picker', CustomTimePickerField::class);
   

2. Event Listeners: Hook into saving or created events to manipulate time values:

   $form->afterStateUpdated(function (array $state, callable $set) {
       if (isset($state['time_slot'])) {
           $set('time_slot', Carbon::parse($state['time_slot'])->format('H:i:s'));
       }
   });
   

3. Accessibility: Add ARIA labels or keyboard shortcuts by extending the Blade view:

   <x-dynamic-component :component="$getFieldWrapperView()" {{ $attributes }}>
       <x-filament-timepicker::time-picker
           wire:model="{{ $getWireModel() }}"
           :min="{{ $getMinTime() }}"
           :max="{{ $getMaxTime() }}"
           :step="{{ $getStep() }}"
           aria-label="{{ $getLabel() }}"
       />
   </x-dynamic-component>