Calendar Bundle Laravel Package

Product Decisions This Supports

• Calendar/scheduling feature scoping. The package remains the request-parsing and event-loading layer behind a calendar UI — the endpoint a frontend calendar library calls to fetch events for a date range. This still informs whether a scheduling surface (resource booking, editorial calendar, availability viewer, internal ops timeline) is a 1–2 sprint feature or a multi-month custom build. v8.3.0 does not change that equation, but it removes two previously-estimated sub-tasks (timezone parameter handling, HTTP caching) from our side of the ledger.
• Build vs. buy for the "boring middle" — now with an upgrade-cost line item. The value is still concentrated in parameter parsing, date-range handling, and response shaping. Adopting it converts a recurring implementation task into a dependency; the counterfactual remains ~1–2 weeks of engineering per calendar surface. v8.3.0 makes the total cost of ownership explicit rather than implicit: the package now requires PHP 8.4+ and Symfony 8, and ships as a breaking release inside the 8.x line. That is a real, quantifiable adoption cost on top of integration — budget a platform-upgrade workstream, not just a spike.
• Roadmap sequencing for calendar-adjacent work. The public contract is still an HTTP endpoint rather than a domain model, so it composes with incremental rollout (read-only view first, then filters, then write paths). It still does not solve persistence, permissions, recurrence, or display-timezone policy — those remain product decisions on our roadmap.
• v8.3.0 partially closes the timezone gap — a product decision gets cheaper. FullCalendar's timeZone parameter is now supported (#102), meaning the endpoint accepts the client's timezone context instead of us translating it in a shim. Combined with ISO 8601-only start/end dates (#149), the transport contract becomes well-defined. What is not solved: our policy for which timezone a calendar defaults to, how users perceive all-day events, and how we display times across regions. Those stay ours, but the plumbing below them is now less custom.
• Caching becomes a product-visible behavior, not just an infra detail. GET support with private ETag revalidation (#101) means the feed can answer 304 Not Modified and avoid re-sending unchanged payloads. For a PM this creates a decision surface: freshness expectations ("why hasn't my calendar updated?"), cache invalidation on write, and the guarantee that private caching respects per-user event visibility. It also directly addresses the previously-flagged scaling concern at realistic event volumes — a genuine roadmap de-risker for high-traffic calendar surfaces.
• Extensibility posture is now settled — and it supports the thin-adapter decision. Making the request parser, serializer, and exception classes final (#147, #148) removes subclass-based customization. That is a constraint if anyone assumed we'd extend the parser to bend the contract. But wiring the controller to parser/serializer interface aliases (#146) preserves the important thing: we can swap implementations through the container. Decision supported: compose and decorate behind our own adapter; do not plan on inheritance.
• Correctness/quality signals remain strong. Immutable date handling across constructors, setters, getters, and listener callbacks (#141–#145) eliminates a class of mutation bugs on the primary data path; the project also raised its mutation-score threshold to 93% (#153) and documents one migration step per change (#151). This supports accepting the dependency at low-to-moderate risk — but a breaking release within the 8.x line, weeks after a patch release, is a cadence signal: pin deliberately and budget recurring upgrade work.

When to Consider This Package

Consider it when:

• You need an event-feed endpoint that answers "give me events between date A and date B, optionally filtered" — the canonical fullcalendar-style contract.
• The calendar is a view over data you already own, not a system of record. The package handles transport, not scheduling semantics.
• Your frontend sends its range/filter payload as a POST body or a GET request — v8.3.0 supports both, and adds private ETag revalidation on the GET path, so cached-feed behavior is available without custom code.
• You need timezone-aware range resolution at the transport layer and want it without writing a shim (v8.3.0+ required for timeZone support).
• You can meet the new platform floor: PHP 8.4 or later and Symfony 8. For a Laravel-first codebase this is the single most important gate — confirm PHP 8.4 is in your hosting/runtime plan and that the Symfony 8 constraint does not collide with the Symfony components Laravel pulls in. Treat framework fit as an explicit evaluation question, not an assumption.
• You want to avoid writing and maintaining date-range/filter parsing, serialization, and cache validation yourself, and are comfortable pinning a dependency for it.

Look elsewhere when:

• You need recurrence rules (RRULE), resource/inventory allocation, conflict detection, booking transactions, or availability logic — none of that is in scope; you'd be building it regardless, and the package's value shrinks relative to total effort.
• You need write operations (create/update/delete events), webhooks, or calendar sync (Google/Microsoft/CalDAV). This is a read-path transport layer.
• You require strict, audited multi-tenant authorization on event visibility — doable, but you'll be adding it above the package. Note that ETag caching must be scoped per-user to avoid leaking visibility; if your authorization model is complex, evaluate whether the remaining scope justifies the dependency.
• You cannot move to PHP 8.4 / Symfony 8 within a reasonable window. Staying on a pre-8.3 pin is defensible, but you then forgo timeZone support and GET/ETag caching, and you carry the earlier request-parsing defect if you are below 8.2.1 — treat the upgrade as a scheduled item, not an indefinite deferral.
• Your integration approach depends on subclassing the parser, serializer, or exception classes — those are now final; you'd be forking.
• Your event volume is large enough that the endpoint's query model becomes a scaling question — profile rather than assume, though the ETag path materially helps here.
• You're on a framework where integration would require wrapping or forking the request lifecycle — the maintenance cost then exceeds the ~1–2 week build.

How to Pitch It (Stakeholders)

To executives (one paragraph): We evaluated a small, actively maintained open-source PHP package that supplies the server-side plumbing behind a calendar view — the part that answers "which events fall in this date range, with these filters." It is not a scheduling engine; it does not store events, handle permissions, recurrence, or booking logic. Its value is narrow and concrete: it removes roughly one to two weeks of undifferentiated engineering per calendar surface and replaces it with a dependency. The new release, v8.3.0, is a feature release with breaking changes: it adds timezone-aware requests, supports GET requests with client-side revalidation (fewer redundant payloads), and tightens date handling and internal quality gates — all of which reduce the custom code we'd otherwise own. It also raises the platform requirement to PHP 8.4 and Symfony 8, so adoption now includes a genuine upgrade workstream alongside the integration spike. Recommendation: approve as a scoped dependency behind a thin internal adapter, fund the PHP 8.4 upgrade as a separate, scheduled line item, and run a short integration spike against v8.3.0 (not an older pin). The package is healthier than at the last review, but it is moving quickly — we should expect to budget an upgrade each minor release rather than assume a one-time integration.

To engineering: Still a request-parsing and event-feed transport layer, not a domain model. v8.3.0 is a breaking release — follow docs/upgrade-to-83.md, which lists one migration step per change. Practical implications: (1) Platform floor — PHP 8.4+ and Symfony 8; validate this against Laravel's component versions and our runtime image before committing, and plan the upgrade explicitly. (2) Timezone — the timeZone parameter (#102) is now accepted and passed through, with immutable request dates handed to listeners (#144); we no longer need our own translation shim, but display/default-timezone policy stays ours. (3) GET + ETag — the feed accepts GET with private ETag revalidation (#101); ensure we never front it with a shared cache, since private is what keeps per-user event visibility safe, and define invalidation on write. (4) Dates — only ISO 8601 start/end are accepted (#149); DateTimeInterface is accepted and immutable dates are returned from getters and constructor/setter paths (#141–#145), which removes a mutation-bug class. Verify our client emits compliant ISO 8601. (5) Extensibility — parser, serializer, and exception classes are final (#147, #148); do not plan on subclassing. Instead, bind the parser/serializer interface aliases (#146) to our own implementations or decorators. This reinforces the existing decision: wrap the endpoint in an application-level adapter with our own DTOs so a swap or fork stays contained. Caveats to validate in the spike: Laravel routing/middleware fit against the Symfony 8 constraint, authorization enforcement on event visibility combined with ETag caching, timezone display policy, and behavior at realistic event volumes with and without cache hits. If the spike shows integration friction exceeding ~2 weeks or the PHP 8.4/Symfony 8 upgrade proves costly, build the thin endpoint ourselves — the scope is genuinely small.