Statamic Calendar Laravel Package

Product Decisions This Supports

• Roadmap and upgrade planning: v0.8.0 is a breaking release for any site relying on the addon’s bundled /calendar route or statamic-calendar/index / statamic-calendar/show templates. Plan migration work before adopting or upgrading: register an app-owned route (e.g. Route::statamic('calendar', 'events/index')), publish examples via php artisan vendor:publish --tag=statamic-calendar-examples, and repoint any collections/routes using the removed templates.
• Build vs. buy / customization strategy: The package is deliberately moving presentation concerns into the host app. That favors teams that want control over routing and templates, but increases upfront integration effort. If you need a drop-in calendar UI with zero template ownership, this release weakens the out-of-box case.
• Feature correctness for taxonomy-driven content: The :tags fix makes tag filtering reliable for terms fields, including single-term configurations (max_items: 1). This supports product use cases like filtered event listings by category, audience, or location.
• Input validation and UX safety: Invalid tags values now throw InvalidArgumentException instead of silently disabling the filter. This is better for catching bad template/config data, but product teams should expect stricter failure modes and add QA coverage for tag parameters.
• Config simplification: Removing the routes key from published config reduces legacy configuration surface. Existing installs should clean up stale config to avoid confusion.

When to Consider This Package

Consider this package if you are building or maintaining a Statamic-powered events/calendar experience and want query/filtering logic handled by the addon while owning your own routes and templates. It is a good fit if your team is comfortable registering Statamic routes, publishing example templates, and maintaining app-level presentation code.

Look elsewhere or defer upgrade if:

• You depend on the old /calendar route or the removed statamic-calendar/index / statamic-calendar/show templates and cannot absorb a migration now.
• You need a fully drop-in calendar UI with no app-side template ownership.
• You rely on permissive tag filtering and cannot handle exceptions from invalid tags values.
• You have a published config/statamic-calendar.php with a routes key and no process to clean it up.

Before upgrading, inventory usages of /calendar, statamic-calendar/index, statamic-calendar/show, and the routes config key. Confirm whether templates published under statamic-calendar-views are in use; those continue to work.

How to Pitch It (Stakeholders)

For executives: v0.8.0 is a correctness and maintainability release, but it includes breaking changes. It fixes tag filtering for events and makes invalid tag values fail loudly instead of silently listing everything. The tradeoff is migration effort: the addon no longer ships a /calendar route or default index/show views, so teams must own routing and templates. Budget a small upgrade task for affected sites and avoid upgrading mid-campaign without QA.

For engineering: Treat v0.8.0 as a breaking upgrade. Remove reliance on the addon’s /calendar route and statamic-calendar/index / statamic-calendar/show templates, publish statamic-calendar-examples as a starting point, repoint routes/collections to app-owned templates, and remove the routes key from published config. Validate :tags behavior against terms fields, including single-term setups, and add tests for invalid tag values now that they throw InvalidArgumentException.