Fullcalendar Laravel Package

Getting Started

This is a Laravel Nova integration for FullCalendar, not a general Laravel package. That single fact should drive your evaluation: if you are not on Nova (and specifically the Nova major version this package targets — check composer.json for laravel/nova constraints before anything else), there is nothing here for you. With 12 stars and zero dependents, treat it as a reference implementation you may end up owning rather than a supported dependency.

Minimal path:

1. composer require horaceho/fullcalendar in a Nova app, then confirm the Nova constraint in composer.json matches your installed Nova version. Mismatches here are the most common install failure.
2. Register the package's field or tool in app/Nova/NovaServiceProvider.php (look at the README's fields() or tools() snippet — the package exposes one or the other, and the registration differs).
3. Publish assets if the README mentions vendor:publish — Nova packages ship compiled JS and often need nova:publish or an asset tag.
4. Open src/ first. With a package this small, the entire surface area is a handful of PHP classes (a Field or Tool, plus a service provider). Reading those 200–400 lines tells you more than the README will. Then look at resources/js/ to see which FullCalendar version is bundled — that determines the options API you get.
5. First use case: put a read-only month view of events on a Nova dashboard or as a detail-page field on a Booking/Event resource, fed from an Eloquent query. Don't start with drag-to-reschedule; start with "can I see my records on a calendar."

If steps 1–3 don't work within an hour, stop. At this maturity level, a broken install usually means the package was built against a Nova version you don't have, and patching around that is a fork, not an integration.

Implementation Patterns

Field-on-a-resource pattern. The most likely intended usage is a Nova field that renders FullCalendar and receives events. Feed it from a closure or method on the field so the data source stays in your app, not the vendor package:

FullCalendar::make('Schedule')
    ->events(fn () => Booking::query()
        ->where('team_id', $request->user()->current_team_id)
        ->get()
        ->map(fn ($b) => [
            'id'    => $b->id,
            'title' => $b->customer_name,
            'start' => $b->starts_at->toIso8601String(),
            'end'   => $b->ends_at->toIso8601String(),
            'url'   => "/resources/bookings/{$b->id}",
        ])),

The url key is the highest-value trick in FullCalendar: it gives you click-through to the Nova detail page for free, without wiring an event-click handler.

Separate the query from the field. Whatever the package's exact API, put event shaping in a dedicated class (App\Calendar\EventSource) and have the field call it. When you fork or replace the package — plan for it — your query logic survives.

Read-only first, mutations later. FullCalendar's editable/drag-and-drop features require a write endpoint and CSRF handling through Nova's axios instance. The package likely does not provide one. If you need drag-to-reschedule, add your own Nova route or use a Nova action instead of drag — actions are idiomatic Nova and require no custom JS.

Multi-model calendars. For a dashboard showing bookings + tasks + holidays, merge sources in PHP into one array with a color or classNames key per source. Do not try to configure three FullCalendar eventSources unless you've verified the package passes raw options through — most thin Nova wrappers only accept a flat event array.

Options passthrough. Whatever the field exposes (->options([...]), ->fullCalendarOptions([...])), test it early with something observable like initialView or locale. If options don't pass through, treat the package as a fixed widget and don't fight it — write a small custom Nova field wrapping FullCalendar yourself and keep the dependency out.

Gotchas and Tips

• Nova version drift is the whole risk. Nova's field/tool APIs changed materially across v3→v4→v5. A 12-star package almost certainly targets one version. Check composer.json and the last commit date before you plan around it.
• No dependents means no bug reports. You are the first person to hit most edge cases. Budget time for reading the bundled JS, and be prepared to composer require horaceho/fullcalendar:dev-main from a fork rather than waiting for upstream.
• Timezone is the classic FullCalendar trap. Send ISO 8601 with offsets from PHP (toIso8601String()), not naive Y-m-d H:i:s. If events land an hour or a day off, it's almost always a naive string plus the browser's local timezone, not a package bug.
• Asset caching after edits. If you modify the package's JS, Nova/browser caching will make you think your change did nothing. Run npm run dev (or prod) in the package if it has a build step, php artisan nova:publish, then hard-reload.
• Debug from the browser console first. FullCalendar warns loudly about malformed events (missing start, bad date strings). Those warnings appear in the console, not in storage/logs/laravel.log. If the calendar renders empty, check the network response for the field's data and the console before touching PHP.
• Serialize dates in the field, not the model. If you add $casts or toArray() overrides to fix a date format, you'll change API responses elsewhere. Shape events at the field boundary.
• Extension point is the field class. Since there's likely no event/hook system, the clean way to customize is to subclass the package's field in app/Nova/, override the method that builds the event payload, and register your class in NovaServiceProvider. That keeps the fork small and upgradeable.
• Exit criteria. If you spend more than a day fighting install, asset publishing, or options passthrough, switch to a first-party or better-maintained alternative (or ~150 lines of custom Nova field + FullCalendar from npm). At 0.18 score and 0 dependents, the package has to earn its place in your composer.json quickly.