Filament Timematrix Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require konnco/filament-timematrix
   

   Publish config (if needed):

   php artisan vendor:publish --provider="Konnco\FilamentTimeMatrix\FilamentTimeMatrixServiceProvider"
   

2. First Usage: Add to a Filament form:

   use Konnco\FilamentTimeMatrix\Forms\TimeMatrix;
   
   TimeMatrix::make('availability')
       ->label('Weekly Availability')
       ->required();
   

   This renders a 7-day (Mon-Sun) × 24-hour grid with bulk selection controls.

3. First Use Case: Create a staff scheduling panel where admins select working hours per day. Example:

   TimeMatrix::make('working_hours')
       ->hours(startTime: 8, endTime: 18) // 8 AM - 6 PM
       ->helperText('Click to mark open hours for each day');
   

Implementation Patterns

Core Workflows

1. Basic Configuration

TimeMatrix::make('field_name')
    ->label('Custom Label')
    ->required()
    ->helperText('Instructions')
    ->columns(5) // Adjust grid columns (default: 7)
    ->rows(12);  // Limit to 12-hour display (default: 24)

2. Dynamic Data Binding

// Form model binding
public function form(Form $form): Form
{
    return $form
        ->schema([
            TimeMatrix::make('hours')
                ->default(fn () => [
                    Day::Monday => [9, 17], // 9 AM - 5 PM
                    Day::Friday => [10, 18],
                ]),
        ]);
}

// Retrieve data
$selectedHours = $record->hours; // Returns array like:
/*
[
    Day::Monday => [9, 17],
    Day::Tuesday => [10, 16],
    // ...
]
*/

3. Validation & Rules

TimeMatrix::make('hours')
    ->rules([
        'required',
        'min_hours:10', // At least 10 hours total
        'max_hours:40', // No more than 40 hours
        'min_days:3',   // At least 3 days selected
    ])
    ->afterStateUpdated(fn (set, $state) => {
        $this->validateRules($state);
    });

4. Multi-Language Support

TimeMatrix::make('hours')
    ->locale('fr'); // Force French (Carbon-based)

5. Custom Styling

TimeMatrix::make('hours')
    ->disabled() // Disable all slots
    ->disabledDays([Day::Saturday, Day::Sunday]) // Disable weekends
    ->selectedClass('bg-blue-500 text-white') // Custom selected slot style
    ->disabledClass('opacity-30'); // Custom disabled slot style

Integration Tips

With Filament Tables

use Konnco\FilamentTimeMatrix\Columns\TimeMatrixColumn;

Table::make()
    ->columns([
        TimeMatrixColumn::make('hours')
            ->label('Schedule')
            ->hours(startTime: 8, endTime: 18),
    ]);

With Livewire Components

public function mount()
{
    $this->form->fill([
        'hours' => [
            Day::Monday => [9, 17],
        ],
    ]);
}

Facade for Validation

use Konnco\FilamentTimeMatrix\Facades\TimeMatrixValidator;

$validator = new TimeMatrixValidator($hoursData);
$validator->validate([
    'min_hours' => 10,
    'max_hours' => 40,
]);

Gotchas and Tips

Pitfalls

1. Data Format Mismatch:

   • Issue: Binding raw data without proper structure causes silent failures.
   • Fix: Ensure data matches [Day::Enum => [startHour, endHour]] format.

     // Correct:
     [Day::Monday => [9, 17]]
     // Incorrect:
     ["Monday" => "09:00-17:00"]
     

2. Time Zone Confusion:

   • Issue: Carbon uses the app’s default timezone. If your app uses UTC, but users expect local time, slots may appear misaligned.
   • Fix: Explicitly set timezone in config:

     'timezone' => 'America/New_York',
     

3. Validation Overrides:

   • Issue: Custom validation rules may conflict with built-in rules.
   • Fix: Use ->ignoreRules() to bypass default validation temporarily.

4. Performance with Large Ranges:

   • Issue: Rendering 24-hour rows × 7 days can be slow in complex forms.
   • Fix: Limit rows/columns:

     ->rows(12) // 12-hour format
     ->columns(5) // Group days
     

5. Dark Mode Inconsistencies:

   • Issue: Custom CSS may break dark mode styling.
   • Fix: Use Filament’s built-in dark classes:

     ->selectedClass('dark:bg-blue-600')
     

Debugging Tips

1. Inspect Raw Data:

   dd($this->data['hours']); // Check bound data structure
   

2. Log Validation Errors:

   $this->form->afterStateUpdated(fn (set, $state) => {
       if ($set === 'hours') {
           $this->dispatch('filament-timematrix::log', [
               'data' => $state,
               'errors' => $this->getErrors(),
           ]);
       }
   });
   

3. Test with Minimal Config: Strip down to basics to isolate issues:

   TimeMatrix::make('test')
       ->required()
       ->hours(); // Default 24-hour range
   

Extension Points

1. Custom Day Labels: Override day names via config:

   'days' => [
       Day::Monday => 'Lundi',
       Day::Tuesday => 'Mardi',
       // ...
   ],
   

2. Slot Templates: Extend Blade templates in resources/views/vendor/filament-timematrix. Example: slot.blade.php for custom hour rendering.

3. Event Listeners: Hook into selection changes:

   TimeMatrix::make('hours')
       ->afterStateUpdated(fn (set, $state) => {
           event(new TimeSlotsUpdated($state));
       });
   

4. API Integration: Serialize/deserialize for external APIs:

   $serialized = json_encode([
       'monday' => ['start' => 9, 'end' => 17],
       // ...
   ]);
   

5. Localization: Extend translations via filament-timematrix.php config:

   'translations' => [
       'en' => [
           'select_all' => 'Mark All',
           'deselect_all' => 'Clear All',
       ],
       'fr' => [
           'select_all' => 'Tout sélectionner',
       ],
   ],