Statamic Calendar Laravel Package

Getting Started

• Install with composer require and publish the example templates first: php artisan vendor:publish --tag=statamic-calendar-examples. Since v0.8.0 the addon no longer ships a working /calendar page, so the examples are your starting point, not optional docs.
• Publish the config (config/statamic-calendar.php) and the base views (--tag=statamic-calendar-views) only if you intend to own and maintain overrides. The examples namespace is the safer reference.
• First use case: an events collection whose blueprint exposes a tags terms field (taxonomy terms), rendered through the addon's calendar tag with :tags="tags", with events/index.antlers.html and events/show.antlers.html living in your app's resources/views.
• Register the routes yourself in routes/web.php — this is now the expected setup, not a workaround:

Route::statamic('calendar', 'events/index');
Route::statamic('calendar/{slug}', 'events/show');

• Look first at the example templates for the expected data shape (event entries, term relationships, date fields), then at the published config for defaults.

Implementation Patterns

• Filtering by terms. Bind the field rather than hand-building a value: {{ calendar :tags="tags" }}. A terms field holding a single term (blueprint max_items: 1) and one holding a query builder both now filter correctly — before v0.8.0 they silently fell through and listed every event, so re-test any listing you had "fixed" with workarounds.
• Route-driven pages. Use Route::statamic() for the listing and detail routes so the templates stay in resources/views and version control, rather than relying on package-shipped views. This also makes per-site route names and middleware straightforward.
• Template ownership. If you were on statamic-calendar/index / statamic-calendar/show, copy or rewrite those into events/index and events/show in your app and point collection routes and Route::statamic() at the app templates. If you had already published statamic-calendar-views, those files keep working — but they're now an orphaned snapshot; plan a migration to app-owned templates.
• Upgrade path for /calendar. Add the route, then grep templates and nav/header partials for hardcoded /calendar links and any statamic-calendar/* template references in collection route settings; both were implicit before and are explicit now.
• Guarding input. If tag values can arrive from user input, a URL segment, or a query string, normalise to term slugs (or resolve to a term/query builder) before binding. v0.8.0 turns bad values into InvalidArgumentException instead of a silently unfiltered listing.

Gotchas and Tips

• Invalid tags now throw. The behaviour change from "filter disabled, list everything" to a thrown InvalidArgumentException is the highest-risk part of this release. Any entry whose tags field contains free text, an ID, an array of mixed values, or imported/garbage data will now 500 the listing instead of quietly degrading. Audit the field values across entries before deploying, and add validation to the blueprint or a normalisation step if the field is loose.
• routes in the config is dead. Remove the key from a published config/statamic-calendar.php; it is no longer read, and leaving it invites someone to "fix" routing by editing a value that does nothing.
• The removed route is a silent 404, not an error. Nothing warns you at boot; you find out in production. Add an assertion or smoke test covering /calendar and a detail URL after upgrading.
• Debugging filters. Dump the raw field value before blaming the tag — an augmented terms field, a raw slug string, and a query builder are all valid inputs, but an unexpected fourth shape (e.g. a YAML list of arrays from an import) is exactly what trips the new exception. Test with max_items: 1 and multi-term field configs, since the two paths differ.
• Cache warm-up. Static/response caching will happily bake in a 500 or stale listing; flush caches after changing templates, routes, or taxonomy terms.
• Extension points. Override rendering by publishing statamic-calendar-views into your app, and treat statamic-calendar-examples as read-only reference material — copying is fine, editing in place is not, since the next publish will overwrite your work.