Timex Laravel Package

Getting Started

Check the Filament version before anything else. The package's history sits in the Filament v2 era; the only release since March 2023 is 1.1.7, and its sole change is a Laravel 10 composer constraint fix — a packaging fix, not a Filament 3 port. If you are on Filament 3 or 4, the plugin interface (Plugin, panel registration, asset handling) changed substantially — confirm compatibility in the README and composer.json constraints before you write a line of code. If it doesn't support your version, budget for a fork rather than an install.

What 1.1.7 does buy you: composer require buildix/timex should now actually resolve on a Laravel 10 app instead of dying in dependency resolution. That is the entire scope of the change — no bug fixes to the calendar, no new API, no Filament 3 support implied. Treat "installs on Laravel 10" and "works with Filament 3" as two separate questions and verify the second yourself.

Minimal path:

composer require buildix/timex:^1.1.7
php artisan vendor:publish --tag=timex-config   # check README for the exact tag
php artisan vendor:publish --tag=timex-assets

Then register the plugin where your panel is configured (in v2 typically app/Providers/FilamentServiceProvider.php or the AdminPanelProvider in later v2.x), and create the calendar page:

php artisan make:filament-page Calendar

Where to look first, in this order:

1. README.md — the only usage documentation that exists; read it end to end, it's short.
2. composer.json — re-check the constraints after installing 1.1.7. Confirm what illuminate/* and filament/* ranges the release actually allows, since that is the only thing this version touched.
3. src/TimexServiceProvider.php — tells you exactly which config keys, views, and asset tags exist. This is more reliable than the README if they disagree.
4. config/timex.php after publishing — the real list of knobs.
5. resources/views/ — the calendar markup; this is your extension surface when you need to change event rendering.

First use case: a Resource-backed month grid. You have a model with a start column (and optionally an end column), you want existing records plotted on a month view, clicking a day opens the standard Filament create form, and clicking an event opens the edit form. That single flow is what this package is for; anything beyond it you will be writing yourself.

Start with one model, one date column, ->dateColumn('starts_at') (or the config equivalent — verify the method name against src/), and confirm the grid renders before adding filters or custom event content.

Implementation Patterns

Resource calendar page. The dominant pattern: a custom Filament page that extends the package's calendar page class, points at a Resource, and delegates create/edit to that Resource's own pages. Keep the calendar as a view over your Resource rather than inventing a parallel event model — you get policies, validation, and notifications for free.

class Calendar extends TimexPage   // verify base class name in src/
{
    protected static string $resource = EventResource::class;
    // date column / end column configured here or via static props
}

Event → Filament action mapping. When a user clicks an event, the expected behaviour is a modal or redirect to the Resource's edit page. Map it explicitly rather than relying on defaults, and make sure the record key (UUID vs autoincrement) matches what the JS layer expects — this is the single most common cause of "clicking an event does nothing."

Scope the query to the visible range. Do not hand the calendar an unbounded Model::all(). Build the query in a modifyQueryUsing()-style hook (or override the data method) with a whereBetween on the date column for the currently displayed window. On any table past a few thousand rows this is the difference between a usable page and a timeout.

->modifyQueryUsing(fn (Builder $q) => $q
    ->whereBetween('starts_at', [$rangeStart, $rangeEnd])
    ->where('team_id', filament()->getTenant()?->id)
)

Custom event rendering. For anything beyond a title — colour by status, badges, truncated descriptions — publish/override the event Blade view and add a color or class accessor on the model. This is cleaner than trying to inject HTML from PHP.

public function getCalendarColorAttribute(): string
{
    return match ($this->status) {
        'confirmed' => '#22c55e',
        'tentative' => '#f59e0b',
        default     => '#94a3b8',
    };
}

Dashboard widget. For a lightweight "this week" panel, embed the calendar as a widget rather than a page. Same query scoping rules apply, and you'll want a compact (week/agenda) default view — a full month grid in a dashboard column is unusable.

Multiple calendars / filters. If you need "my events" vs "team events" vs "holidays," model each as a separate query source and render them with distinct colours plus a legend. Filament's Filter API on the page works, but the calendar must re-fetch on filter change — confirm the Livewire round-trip actually re-queries and isn't serving a cached payload.

Integration with existing Resource tables. A good pattern is a "List / Calendar" toggle on the same Resource: the table for bulk operations, the calendar for scheduling. Share the same getEloquentQuery() so authorization scoping is identical in both views.

Gotchas and Tips

1.1.7 is a dependency-resolution patch, not a maintenance signal. The release fixes the Laravel 10 composer require and nothing else — no calendar fixes, no Filament 3 work, no new features. Practically: bump from a dev pin to "buildix/timex": "^1.1.7" (or your fork's equivalent) so a clean composer install on Laravel 10 succeeds, but do not read this as "the package is active again." There is still no release cadence, no docs site, and effectively no dependents. If you need a fix, you are still the maintainer — fork it, tag your own version, and read the source, because the code is the documentation.

Pin deliberately, either way. A caret on ^1.1.7 is fine now that the Laravel 10 constraint is corrected. If you fork, pin "yourvendor/timex": "dev-main#<sha>" or a VCS repository entry so a future composer update can't silently change behaviour.

The Laravel 10 fix does not imply Filament 3 support. It's tempting to infer "Laravel 10 → modern → Filament 3 works." Don't. Grep the source for Filament imports and class names before committing; if the plugin registration and page base classes are still v2 signatures, the app will fail at boot on a v3 panel regardless of what composer allowed through.

Asset publishing is version-sensitive. Filament v2 vs v3 differ in how JS/CSS are registered and whether you run php artisan filament:assets, vendor:publish, or a Mix/Vite build. If the calendar renders as unstyled markup, the assets tag never resolved — check TimexServiceProvider for the literal tag string.

Timezone and DST. Calendar plugins universally get this wrong at the boundaries. Store timestamps in UTC, cast explicitly on the model, and pin the display timezone in config rather than trusting the server default. Test a DST transition month — events landing an hour off is the classic symptom.

Date column type matters. A date cast (no time) and a datetime cast behave differently when the JS layer buckets events into days. If events appear on the wrong day, this is almost always the cause, not the timezone.

All-day and multi-day events. Support here is usually the weakest part of any small calendar package. Verify multi-day spanning renders correctly before you promise it to stakeholders; be prepared to flatten to per-day rows in the query if not.

Navigation re-renders are Livewire round-trips. Each month change is a request. Guard against: (a) unbounded queries, (b) N+1 loading relations in the event accessor, (c) recomputing expensive aggregates on every render. Cache per-range results if the page feels sluggish.

Authorization still flows through your Resource. The calendar is a presentation layer — it does not bypass policies. But double-check that create-on-day-click respects create policy; small plugins frequently wire the click handler straight to the form.

Extension points, in order of safety: publish the config → override the Blade event view → subclass the page and override the data method → fork. Avoid editing vendor/ at all costs.

Localization. Week-start day and month names come from Filament's locale or a package config key — check which. A Monday-start grid that shows Sunday first is a config miss, not a bug.

Debugging tip: dump the JSON payload the page hands to the JS layer (the property holding the events array). Nine times out of ten, "the calendar is broken" means the payload is empty or the date keys are in the wrong format — you'll spot both instantly from the dump.