Filament Business Hours Laravel Package

Getting Started

Minimal Setup

1. Installation: Run composer require zedmagdy/filament-business-hours in your Laravel project.
2. Register Plugin: Add the plugin to your PanelProvider with a timezone (e.g., 'Asia/Riyadh').
3. Database Migration: Add a json column (e.g., business_hours) to your model’s table.
4. Model Configuration: Use the HasBusinessHours trait and cast the column as array in your model.

First Use Case

Add a BusinessHoursField to a Filament form for a model (e.g., Branch):

BusinessHoursField::make('business_hours')
    ->columnSpanFull();

This renders a UI for defining daily business hours (e.g., 9 AM–5 PM) with timezone support.

Implementation Patterns

Workflows

1. CRUD Integration:

   • Use BusinessHoursField in Filament forms for editing/creating records.
   • Display hours in tables with BusinessHoursColumn:

     BusinessHoursColumn::make('business_hours')
         ->formatStateUsing(fn ($state) => $state['timezone'] ?? 'UTC');
     

2. Validation:

   • Validate hours via the trait’s built-in rules (e.g., required|business_hours).
   • Customize validation by extending the trait or using Laravel’s validation rules.

3. Timezone Handling:

   • Set a default timezone in the plugin registration or per-field:

     ->defaultTimezone('America/New_York')
     

   • Store timezone data in the JSON column for consistency.

4. Exceptions:

   • Enable exceptions in the field:

     ->allowExceptions()
     

   • Exceptions (e.g., holidays) are stored as an array in the JSON column.

Integration Tips

• Model Events: Listen for saving/saved events to log changes to business hours.
• API Responses: Format hours for APIs using accessors:

  public function getBusinessHoursAttribute($value) {
      return json_decode($value, true);
  }
  

• Localization: Translate UI labels (e.g., "Exceptions") via Filament’s localization system.

Gotchas and Tips

Pitfalls

1. JSON Column Quirks:

   • Ensure your database supports JSON columns (MySQL 5.7+, PostgreSQL).
   • Avoid manual JSON string manipulation; use the trait’s methods (e.g., setBusinessHours()).

2. Timezone Mismatches:

   • If timezones aren’t set, hours may display incorrectly. Always specify a default in the field or plugin.
   • Store timezone data in the JSON column to preserve it across edits.

3. Exceptions Overlap:

   • The package doesn’t validate overlapping exceptions. Add custom validation if needed:

     $this->validateBusinessHoursExceptions();
     

4. Caching:

   • Business hours are stored as JSON; avoid caching the entire model if hours change frequently.

Debugging

• Empty Data: Check if the JSON column is null or malformed. Use dd($model->business_hours) to inspect.
• UI Issues: Clear Filament’s cache (php artisan filament:cache:clear) if the field renders incorrectly.
• Timezone Errors: Verify the timezone string matches PHP’s supported timezones (e.g., Asia/Riyadh).

Extension Points

1. Custom Fields:

   • Extend BusinessHoursField to add features (e.g., recurring exceptions):

     class CustomBusinessHoursField extends BusinessHoursField {
         protected function getExtraAttributes(): array {
             return ['recurring' => true];
         }
     }
     

2. Validation Rules:

   • Add custom rules to the trait:

     public function validateBusinessHours($attribute, $value, $fail) {
         // Custom logic
     }
     

3. Table Actions:

   • Add actions to toggle exceptions or copy hours between records:

     Tables\Actions\Action::make('copyHours')
         ->action(function (Branch $record) {
             // Logic to duplicate hours
         });