Filament Fullcalendar Laravel Package

Technical Evaluation

Architecture fit. The prior assessment's core premise — "thin presentation adapter, not a scheduling engine" — no longer holds for the v5 line, and that is the single most important change in this release. v4 was a render adapter: you supplied DTOs, you persisted mutations. v5 pulls three responsibilities into the package:

• Model-backed events. Models can describe their own calendar representation, and one calendar can hold events backed by different models, with the package tracking which record each event represents and resolving the appropriate model, policy, label and actions on open. This is a domain contract, not a view concern.
• Persistence semantics. Mapping start/end attributes to a model lets the package persist drag/resize automatically, optionally gated by a confirmation step. That is a write path the package owns the trigger for.
• Data sourcing. External iCalendar and Google Calendar feeds are rendered read-only alongside application events, with private iCal URLs fetched server-side rather than exposed to the browser.

The Filament-native redesign (toolbar composition, Filament buttons/badges/colors, heading/description/header actions, filters and tabs as first-class features with remembered state, Filament actions for create/view/edit/delete with automatic refresh) is genuinely good architecture for the admin-panel use case — it removes duplication between resources and the calendar, and it reuses policies and schemas rather than inventing parallel machinery. But it also means the integration surface is now considerably larger and the package sits closer to your domain layer than before.

Two architectural consequences deserve explicit sign-off:

• Polymorphic event identity. "One calendar, many models" means per-event policy resolution across model types. Correctness now depends on the package resolving the right policy per record, and on your policies being complete for every model you register. A calendar mixing two models with different authorization shapes is an authorization surface, not a rendering choice.
• A server-side outbound fetch component. iCal fetching from your application introduces egress, credential storage (Google), caching, and SSRF exposure where none existed in v4. This is new operational surface that does not appear in a "calendar widget" mental model.

Still absent or unstated after this release: any recurrence engine, and any explicit timezone resolution contract. Do not assume v5 solves either. The verdict shape is unchanged — good fit for internal operations calendars inside a Filament panel; poor fit for API-first, headless, or Inertia/Vue surfaces — but the "thin adapter" mitigation that previously made fork-and-vendor cheap is now materially more expensive.

Integration feasibility. v5 is no longer a composer-only upgrade, and the release notes are unusually candid about it. The migration path is a Rector-based codemod (vendor/bin/filament-fullcalendar-v5) that rewrites v4 widgets and their tests without booting the application, handling handler signatures, record APIs, deprecated actions, getFormSchema(), test call sites, and an optional preservation of v4 create-button behaviour. It supports --dry-run and prints a residual manual checklist.

That is a real accelerator and a genuine maturity signal — an upgrade assistant is what you build when you expect a large installed base to move. It is also a governance item: a tool that mechanically edits your source tree is a change you review, not a change you trust. Budget for reading the diff.

Feasibility by scope:

• API parity upgrade (v4 behaviour on v5 API): 1–2 days including dry-run, diff review, manual checklist, and a smoke test. This is the recommended first move.
• Adopting model-backed events: 1–2 days plus per-model work; benefit is real (removes DTO duplication) but it deepens coupling to the package's contract.
• Drag/drop auto-persist: 1 day plus policy/validation review, because you are delegating a write trigger.
• Filters and tabs: 0.5–1 day per calendar surface, plus query-performance review since tabs can modify queries.
• Resource calendars: 1–2 days, and see the licensing warning below.
• External calendars (iCal / Google): 1–3 days, dominated by security and credential work rather than calendar work.

The maintainer states GA is expected roughly a week after beta1 and that no further breaking changes are planned. If that timeline holds, waiting for GA costs almost nothing and removes beta risk from the critical path — which matters because the beta3 regression (click/drag/resize on calendars without resource views) demonstrated that the interaction path is exactly where breakage lands.

Technical risk. The dominant risk is still dual upstream coupling (package major and FullCalendar major now version independently; v5 targets FullCalendar 7), and this release adds several new risk classes on top:

• Licensing exposure increases materially. Resource calendars now have a first-class PHP API, which is an explicit invitation toward FullCalendar's premium resource/timeline views. The package making resources easy does not make them licensed. Confirm entitlement and schedulerLicenseKey() handling for FullCalendar 7 before anyone builds a resource calendar in a sprint.
• Codemod correctness. An AST rewrite that runs without booting the app cannot validate runtime behaviour. Mechanical rewrites of handler signatures and test calls can produce code that compiles and tests that pass while semantics drift. Treat the script's output as a candidate patch.
• Server-side fetch security. iCal URLs are fetched by the application, which is the right call for privacy but is textbook SSRF surface if the URL is user-supplied. Requires an allowlist/scheme policy, timeout, size cap, and no-redirect-to-internal handling.
• Credential handling for Google Calendar. OAuth tokens for a third-party calendar become a new secret class to store, rotate, and revoke.
• Implicit write path. Auto-persist on drag/resize must still be re-validated server-side against policy and business rules; confirmation mode is a UX guardrail, not an authorization control.
• Mixed-model authorization. Multi-model calendars concentrate policy risk in a single view.
• Beta status and doc drift. Notes are labelled beta1 while the tracked tag is beta4; the README already points at branch-scoped 5.x docs. Reconcile which features exist at which tag before scoping, and treat the documentation as moving.
• Upgrade step still isn't composer-only. composer update plus php artisan filament:assets remains mandatory; any pipeline caching panel assets will silently serve stale JS otherwise.
• Unstated constraints persist. Filament/Livewire/PHP/Laravel floors, deprecation policy, security disclosure channel, and CI matrix remain unstated. The maintainer's own acknowledgement of a "less-than-ideal maintenance cycle" is honest and welcome, and it is also a confirmation of the historical risk rather than a mitigation of it.

Key questions for the maintainer / due diligence:

1. What are the exact Filament, Livewire, Laravel, PHP and FullCalendar constraints for v5, and what is the v4.x support window post-GA (security-only or bug fixes)?
2. Is the model-event contract (interfaces, attribute mapping, multi-model identity) stable at GA, and is it versioned separately from the widget API?
3. Does drag/drop auto-persist route through policies, validation and model events, and can it be disabled globally per widget?
4. What SSRF protections, timeouts, caching and failure behaviour govern iCal fetching? Is there a documented allowlist mechanism?
5. How are Google Calendar credentials stored and scoped, and what is the revocation path?
6. Does v5 change premium-view licensing or schedulerLicenseKey() handling for FullCalendar 7, and does the resources API require a licensed view?
7. Is there a CI matrix and browser-level test covering click-open, drag and resize on a non-resource calendar (the beta3 regression path), and do the shipped tests cover the codemod's output?
8. Recurrence and timezone: explicitly out of scope, or planned?
9. Is there a security policy, disclosure channel, and funded or co-maintainer path?

Verdict (revised): the earlier "adopt v4.x stable, don't run v5 beta in production" holds, but the reasoning behind it has changed from "the beta is immature" to "the beta is immature and the surface it adds is much larger than a theming change." Hold production on v4.x stable, start the v5 spike now using the codemod in --dry-run against a branch, and plan the upgrade for shortly after GA rather than during the beta. The multi-model event contract and the external-feed components are the two areas needing an explicit architectural decision and a named owner before adoption, not after.

Integration Approach

Stack fit. v4.x remains PHP 8.1+, Laravel 10/11, Filament 3.x, Livewire 3, with events rendered through Filament Actions so authorization and validation reuse existing machinery. That is still the recommended production line. For v5, the shape of the fit is now better — Filament-native toolbar, filters, tabs, headings, actions and schemas mean a calendar surface behaves like a resource list, which is a real reduction in bespoke code — but the exact floors are unverified and plausibly higher (Filament major, FullCalendar 7). Read composer.json at the target tag before estimating anything. Theming remains panel-plugin scoped and does not change the admin-only positioning.

Migration path. Sequence matters more than it did before, because the codemod is a one-shot rewrite and the new features are optional:

1. Production stays on v4.x. No change required from this release.
2. Codemod dry-run on a branch (0.5 day). Install the beta tag, run vendor/bin/filament-fullcalendar-v5 --dry-run, and read the full diff. This is the cheapest possible signal about how much of your widget code the script touches and where it leaves manual work.
3. Apply the codemod on a feature branch (0.5–1 day). Follow the documented ordering exactly (package install may error on discovery against un-upgraded widgets; Rector installed with --no-scripts). Run the printed manual checklist. Build assets, run php artisan filament:assets, and execute the interaction smoke script: render read-only, click-open, edit, drag, resize — on a calendar without resource views, which is the configuration the beta3 defect hit.
4. Feature-parity freeze (0.5 day). Before adopting any new capability, confirm the calendar behaves identically to v4. Do not mix migration with feature adoption.
5. Adopt new capabilities one at a time, each as its own PR: model-backed events → drag/drop auto-persist → filters/tabs → resources → external calendars. External calendars go last; they are a security project, not a UI project.

Guardrail change. The old rule was "Eloquent is the single source of truth and EventData is the anti-corruption boundary." That boundary is now optional, and adopting the package's model contract is the whole point of moving to v5. The updated guardrail: adopt the model contract where it removes duplication, but keep one seam you own — a trait, base class or small adapter — so that if the package's contract changes at v5.1 or v6, the change is contained to that seam rather than smeared across every model. Keep an escape hatch to DTOs, and do not let the package's attribute-mapping configuration become the only place your scheduling invariants are expressed.

Compatibility. Pin the package to an exact minor and record the FullCalendar major separately (package and JS versions no longer correspond). Ensure php artisan filament:assets runs in every deploy that updates the package, and treat asset/package version mismatch as a deploy failure. If themes or external calendars are adopted, fail the Vite build when the theme manifest entry is absent, and fail the deploy when outbound-fetch configuration is missing.

Sequencing summary (v5 evaluation and upgrade, ~3–4 days to parity, 2–5 further days for optional capabilities):

1. Constraint check against the tag's composer.json — 0.25 day. If it forces a Filament major, scope that as a panel upgrade program, not a calendar ticket.
2. Codemod dry-run and diff review — 0.5 day.
3. Codemod apply on a branch plus manual checklist — 0.5–1 day.
4. Parity smoke test (click/drag/resize, non-resource calendar) — 0.5 day.
5. Optional capability evaluation, one per PR — 2–5 days depending on scope, with external calendars requiring a security review sign-off.
6. Decision and write-up, with rollback (stay on v4.x) documented — 0.25 day.

Operational Impact

Maintenance. You now own more than a widget subclass. The maintenance ledger reads: package minor line, FullCalendar major, panel asset build, the upgrade codemod's diff output, an event-model contract, and — if adopted — theme modules, external-feed credentials and outbound fetch policy. That is a meaningful step up from "one adapter class." The upside is real: less bespoke glue, Filament-native behaviour, filters/tabs you no longer hand-build. The trade is that the calendar is now a subsystem with dependencies on your domain models and your network egress. Assign an owner for each adopted capability before adopting it; an unowned model contract becomes an upgrade blocker and an unowned Google OAuth token becomes an incident.

Support. MIT, community-supported, no SLA, no escalation path. The release notes are a strong positive signal — an automated upgrade script, a clear GA timeline, a candid acknowledgement of past maintenance, and an open invitation for PRs against 5.x. That is better hygiene than the prior assessment assumed. It is still not a support commitment, and a single-maintainer project mid-major is churn by definition. Keep the integration surface thin enough that fork-and-vendor remains a weekend, not a quarter; the addition of model contracts and feed handling lengthens that weekend, which is the argument for the owned seam described above.

Scaling. Unchanged at the rendering layer — FullCalendar renders client-side, so the ceiling is events-per-view and Livewire payload size, not RPS. Keep the existing guardrails: filter by the supplied date window in the event source, index start/end columns, cap events per window with an aggregate fallback, cache windowed payloads for shared ranges. New scaling considerations from this release:

• Mixed-model calendars can generate N+1 queries and per-event policy checks. Load relations eagerly and measure query count with a realistic multi-model calendar before shipping.
• Filter and tab state that modifies queries moves filtering to the server, which is good for payload size but concentrates load on the query layer — index the fields your tabs filter on.
• External feeds are fetched server-side and must be cached with a TTL and a circuit breaker. An uncached iCal fetch on every widget render turns a third party's availability into your page latency.
• Confirmation-gated drag/drop is a cheap way to keep write volume low while you build confidence in the persistence path.

Failure modes and mitigations:

Ramp-up. Higher than v4, and it scales with how much of the new surface you adopt. Baseline for a Filament-fluent developer: ~1 day to a working calendar. Add ~1–2 days for v5 concepts (Filament actions, schemas, model event contracts) and ~0.5 day to run and review the codemod. Per-capability: filters/tabs ~0.5–1 day; drag/drop auto-persist ~1 day including validation review; resource calendars ~1–2 days; external calendars ~1–3 days, mostly security and credential work rather than calendar work; theme authoring ~0.5–1 day if used. A Laravel developer new to Filament should add 1–2 days on top of the baseline. The genuinely non-obvious work is still the domain layer the package does not solve — recurrence semantics, timezone conventions, and the business rules behind drag/drop — and v5's tighter model coupling makes those rules more visible in your codebase, not less necessary.