README

Filament Time Matrix

An interactive Filament form component for selecting time slots across days with powerful validation and manipulation features.

Features

📅 Interactive day/hour matrix with bulk selection
✅ Select all hours/days/slots at once
🔄 Reset functionality
🔢 Real-time slot counter
🛠️ Facade for validation & manipulation
🌍 Multi-language support via Carbon
🎨 Dark mode support

Requirements

PHP: 8.1 or higher
Filament: 3.0 or higher
Laravel: 10.0 or 11.0 or higher
Carbon: 2.0 or 3.0 or higher

Installation

composer require konnco/filament-timematrix

Quick Start

Simple Usage

use Konnco\FilamentTimeMatrix\Forms\TimeMatrix;

TimeMatrix::make('schedule')
    ->label('Select Schedule')
    ->required();

This will create a time matrix with:

All 7 days of the week (Monday - Sunday)
All 24 hours (0-23)
Select all hours/days buttons enabled
Using your app's default locale

Complete Usage

use Konnco\FilamentTimeMatrix\Forms\TimeMatrix;
use Konnco\FilamentTimeMatrix\Enums\Day;
use Carbon\CarbonInterface;

TimeMatrix::make('schedule')
    ->label('Select Schedule')
    ->required()
    ->helperText('Select operational hours for each day')
    
    # Set custom hour range (9 AM - 5 PM)
    ->hours(startTime: 9, endTime: 17)

    # OR use business hours shortcut with default range from 9 AM - 5 PM
    ->businessHours()
    
    # Set specific days using Day enum
    ->days([
        Day::MONDAY,
        Day::TUESDAY,
        Day::WEDNESDAY,
    ])
    # OR use Carbon constants
    ->days([
        CarbonInterface::MONDAY,
        CarbonInterface::SATURDAY,
    ])
    # OR use helper methods
    ->weekdays() # Monday - Friday only
    ->weekend()  # Saturday - Sunday only
    
    # Set locale and format
    ->locale('id', 'long')  # long: Monday, short: Mon,
    ->locale('en', 'short')
    
    # Toggle select all buttons
    ->showSelectAllHours(false)
    ->showSelectAllDays(false)
    
    ->columnSpanFull();

Available Methods

Method	Description	Example
`hours(int $startTime, int $endTime)`	Set custom hour range (0-23)	`->hours(8, 18)`
`businessHours(int $startTime, int $endTime)`	Shortcut for business hours	`->businessHours(9, 17)`
`days(array $days)`	Set specific days (Day enum or Carbon constants)	`->days([Day::MONDAY, Day::FRIDAY])`
`weekdays()`	Monday to Friday only	`->weekdays()`
`weekend()`	Saturday and Sunday only	`->weekend()`
`locale(?string $locale, string $format)`	Set locale and format (long/short/min)	`->locale('id', 'short')`
`showSelectAllHours(bool $show)`	Show/hide select all hours button	`->showSelectAllHours(false)`
`showSelectAllDays(bool $show)`	Show/hide select all days button	`->showSelectAllDays(false)`

Facade Methods Reference

`isActiveAt(array $data, ?Carbon $dateTime = null): bool`

Check if time slot is active at a specific time or now (default).

Parameters:

$data (array): The time matrix data
$dateTime (Carbon|null, optional): DateTime to check. Defaults to now()

Returns: bool

Examples:

use Konnco\FilamentTimeMatrix\Facades\TimeMatrix;
use Carbon\Carbon;

$data = ['monday' => [8 => true, 9 => true]];

# Check if active right now
TimeMatrix::isActiveAt($data);

# Check if active at specific time
TimeMatrix::isActiveAt($data, Carbon::parse('next monday 8:00')); # true
TimeMatrix::isActiveAt($data, Carbon::tomorrow()->setTime(14, 0)); # true/false

# Check if active 2 hours from now
TimeMatrix::isActiveAt($data, now()->addHours(2));

`hasActiveDay(array $data, string|Day|null $day = null): bool`

Check if there are active slots on a specific day or today (default).

Parameters:

$data (array): The time matrix data
$day (string|Day|null, optional): Day to check. Defaults to today

Returns: bool

Examples:

use Konnco\FilamentTimeMatrix\Enums\Day;
use Carbon\Carbon;

$data = [
    'monday' => [8 => true],
    'tuesday' => [14 => true],
];

# Check if active today (no parameter needed!)
TimeMatrix::hasActiveDay($data); # true/false

# Check specific days
TimeMatrix::hasActiveDay($data, Day::MONDAY);
TimeMatrix::hasActiveDay($data, 'tuesday'); 
TimeMatrix::hasActiveDay($data, Day::WEDNESDAY); 

# Check tomorrow
TimeMatrix::hasActiveDay($data, Day::fromCarbon(Carbon::tomorrow()));

`getActiveHours(array $data, string|Day|null $day = null): array`

Get active hours for a specific day or today (default).

Parameters:

$data (array): The time matrix data
$day (string|Day|null, optional): Day to get hours from. Defaults to today

Returns: array - Array of hours like [8, 9, 10, 14, 15]

Examples:

use Konnco\FilamentTimeMatrix\Enums\Day;

$data = [
    'monday' => [8 => true, 9 => true, 14 => true],
    'tuesday' => [10 => true, 11 => true],
];

# Get today's active hours
TimeMatrix::getActiveHours($data); # [8, 9, 14] 

# Get specific day's hours
TimeMatrix::getActiveHours($data, Day::MONDAY); # [8, 9, 14]
TimeMatrix::getActiveHours($data, 'tuesday'); # [10, 11]

# Get tomorrow's hours
TimeMatrix::getActiveHours($data, Day::fromCarbon(Carbon::tomorrow()));

# Loop through today's hours
foreach (TimeMatrix::getActiveHours($data) as $hour) {
    echo sprintf('%02d:00 - Available', $hour);
}

Validation Methods

`validate(array $data): bool`

Validate the structure of time matrix data.

Example:

$valid = ['monday' => [8 => true, 9 => false]];
TimeMatrix::validate($valid); # true

$invalid = ['monday' => 'not an array'];
TimeMatrix::validate($invalid); # false

`hasSelection(array $data): bool`

Check if there is at least one selected slot.

Example:

$data = ['monday' => [8 => true, 9 => false]];
TimeMatrix::hasSelection($data); # true

$empty = ['monday' => [8 => false]];
TimeMatrix::hasSelection($empty); # false

Statistics Methods

`isFullyActive(array $data): bool`

Check if schedule is 24/7 (all days, all hours).

Example:

TimeMatrix::isFullyActive($data); # true/false

`getTotalActiveHours(array $data): int`

Get total active hours per week.

Example:

$total = TimeMatrix::getTotalActiveHours($data); # e.g., 40

`getActivePercentage(array $data): float`

Get percentage of active hours (0-100).

Example:

$percentage = TimeMatrix::getActivePercentage($data); # e.g., 23.81

`getActiveDays(array $data): array`

Get days that have at least one active hour.

Returns: Array of Day enums

Example:

$days = TimeMatrix::getActiveDays($data);
# [Day::MONDAY, Day::TUESDAY, Day::FRIDAY]

foreach ($days as $day) {
    echo $day->label(); # Monday, Tuesday, Friday
}

`isDayHourActive(array $data, string|Day $day, int $hour): bool`

Check if a specific day and hour combination is active.

Example:

TimeMatrix::isDayHourActive($data, day: Day::MONDAY, hour: 9); # true/false
TimeMatrix::isDayHourActive($data, day: 'friday', hour: 18); # true/false

Time Query Methods

`getNextAvailableSlot(array $data, Carbon $from): ?Carbon`

Get next available slot from a specific time.

Example:

$next = TimeMatrix::getNextAvailableSlot($data, now());
if ($next) {
    echo $next->format('l, H:i'); # "Monday, 08:00"
}

`getSlotsInRange(array $data, Carbon $start, Carbon $end): array`

Get all slots within a date range.

Example:

$slots = TimeMatrix::getSlotsInRange(
    $data,
    now()->startOfWeek(),
    now()->endOfWeek()
);

foreach ($slots as $slot) {
    echo $slot->format('D H:i') . "\n";
}

`toCarbonSlots(array $data, ?Carbon $referenceWeek = null): array`

Convert to Carbon instances for a specific week.

Example:

# Current week
$slots = TimeMatrix::toCarbonSlots($data);

# Next week
$nextWeek = now()->addWeek();
$slots = TimeMatrix::toCarbonSlots($data, $nextWeek);

Formatting Methods

`toReadableFormat(array $data): array`

Convert to simplified format.

Returns: ['monday' => [8, 9, 10], 'tuesday' => [14, 15]]

Example:

$readable = TimeMatrix::toReadableFormat($data);

`formatDaySchedule(array $data, string|Day $day): string`

Format single day to human-readable string.

Returns: String like "08:00-10:59, 14:00-16:59"

Example:

$schedule = TimeMatrix::formatDaySchedule($data, Day::MONDAY);
# "08:00-10:59, 14:00-16:59"

`formatAllDays(array $data, ?string $locale = null): array`

Format all days with localized labels.

Example:

$formatted = TimeMatrix::formatAllDays($data, 'en');
# [
#     'Monday' => '08:00-10:59, 14:00-16:59',
#     'Tuesday' => '14:00-15:59'
# ]

$formatted = TimeMatrix::formatAllDays($data, 'id');
# [
#     'Senin' => '08:00-10:59, 14:00-16:59',
#     'Selasa' => '14:00-15:59'
# ]

Real-World Usage Examples

1. Check Merchant Status

use Konnco\FilamentTimeMatrix\Facades\TimeMatrix;

class StoreService
{
    public function getOpenStores()
    {
        return Store::all()->filter(function ($store$) {
            # No parameter = check now!
            return TimeMatrix::isActiveAt($store$->operational_hours);
        });
    }
    
    public function countOpenNow(): int
    {
        return Store::get()->filter(fn($store) => 
            TimeMatrix::isActiveAt($store->operational_hours)
        )->count();
    }
    
    public function getOpenTomorrow()
    {
        return Store::get()->filter(fn($store) =>
            TimeMatrix::hasActiveDay(
                $store->operational_hours,
                Day::fromCarbon(Carbon::tomorrow())
            )
        );
    }
}

2. Display in Infolist

use Filament\Infolists\Components\TextEntry;

TextEntry::make('schedule')
    ->label('Status Now')
    ->state(fn($record) => TimeMatrix::isActiveAt($record->schedule) 
        ? '✓ Open' 
        : '✗ Closed'
    )
    ->badge()
    ->color(fn($record) => TimeMatrix::isActiveAt($record->schedule) 
        ? 'success' 
        : 'danger'
    ),

TextEntry::make('schedule')
    ->label('Today\'s Hours')
    ->state(function ($record) {
        $hours = TimeMatrix::getActiveHours($record->schedule); # Today by default!
        return empty($hours) 
            ? 'Closed today'
            : implode(', ', array_map(fn($h) => sprintf('%02d:00', $h), $hours));
    }),

API Methods Summary

Smart Default Methods (NEW!)

Method	Default Behavior	Usage
`isActiveAt($data, ?$dateTime)`	Checks now if no param	`isActiveAt($data)`
`hasActiveDay($data, ?$day)`	Checks today if no param	`hasActiveDay($data)`
`getActiveHours($data, ?$day)`	Gets today's hours if no param	`getActiveHours($data)`

All Available Methods

Method	Return Type	Description
`validate($data)`	`bool`	Validate structure
`hasSelection($data)`	`bool`	Check if has selections
`isActiveAt($data, ?$dateTime)`	`bool`	Check active at time (default: now)
`hasActiveDay($data, ?$day)`	`bool`	Check day has active slots (default: today)
`getActiveHours($data, ?$day)`	`array`	Get active hours (default: today)
`isFullyActive($data)`	`bool`	Check if 24/7
`getTotalActiveHours($data)`	`int`	Total hours per week
`getActivePercentage($data)`	`float`	Coverage percentage
`getActiveDays($data)`	`array<Day>`	Days with active slots
`isDayHourActive($data, $day, $hour)`	`bool`	Check specific day+hour
`getNextAvailableSlot($data, $from)`	`?Carbon`	Next available slot
`getSlotsInRange($data, $start, $end)`	`array<Carbon>`	Slots in range
`toCarbonSlots($data, ?$week)`	`array<Carbon>`	Convert to Carbon
`formatDaySchedule($data, $day)`	`string`	Format single day
`formatAllDays($data, ?$locale)`	`array`	Format all days
`toReadableFormat($data)`	`array`	Simplified format

konnco / filament-timematrix

Maintainers

Details

README

Filament Time Matrix

Features

Requirements

Installation

Quick Start

Simple Usage

Complete Usage

Available Methods

Facade Methods Reference

isActiveAt(array $data, ?Carbon $dateTime = null): bool

hasActiveDay(array $data, string|Day|null $day = null): bool

getActiveHours(array $data, string|Day|null $day = null): array

Validation Methods

validate(array $data): bool

hasSelection(array $data): bool

Statistics Methods

isFullyActive(array $data): bool

getTotalActiveHours(array $data): int

getActivePercentage(array $data): float

getActiveDays(array $data): array

isDayHourActive(array $data, string|Day $day, int $hour): bool

Time Query Methods

getNextAvailableSlot(array $data, Carbon $from): ?Carbon

getSlotsInRange(array $data, Carbon $start, Carbon $end): array

toCarbonSlots(array $data, ?Carbon $referenceWeek = null): array

Formatting Methods

toReadableFormat(array $data): array

formatDaySchedule(array $data, string|Day $day): string

formatAllDays(array $data, ?string $locale = null): array

Real-World Usage Examples

1. Check Merchant Status

2. Display in Infolist

API Methods Summary

Smart Default Methods (NEW!)

All Available Methods

License

Credits

Support

`isActiveAt(array $data, ?Carbon $dateTime = null): bool`

`hasActiveDay(array $data, string|Day|null $day = null): bool`

`getActiveHours(array $data, string|Day|null $day = null): array`

`validate(array $data): bool`

`hasSelection(array $data): bool`

`isFullyActive(array $data): bool`

`getTotalActiveHours(array $data): int`

`getActivePercentage(array $data): float`

`getActiveDays(array $data): array`

`isDayHourActive(array $data, string|Day $day, int $hour): bool`

`getNextAvailableSlot(array $data, Carbon $from): ?Carbon`

`getSlotsInRange(array $data, Carbon $start, Carbon $end): array`

`toCarbonSlots(array $data, ?Carbon $referenceWeek = null): array`

`toReadableFormat(array $data): array`

`formatDaySchedule(array $data, string|Day $day): string`

`formatAllDays(array $data, ?string $locale = null): array`