Laravel Calendar Laravel Package

Product Decisions This Supports

• Build vs. buy on calendar UI. 2.0.0 shifts the calculus: Calendar::registerModel() + HasCalendarEvents with EloquentEventProvider/EloquentActionHandler means the calendar can render your existing domain models (tasks, classes, deliveries) instead of forcing a parallel calendar_events table. That removes the largest hidden cost of adoption — the sync layer and its reconciliation bugs — so "buy/adopt" now beats an in-house build for most roadmap timelines.
• Roadmap sequencing for scheduling features. Model-level recurrence via EloquentSeries makes recurring business entities (a class that meets weekly, a delivery that repeats) a configuration concern rather than a custom feature project. Recurring-events epics can be re-scoped down or deferred in favor of higher-value differentiation.
• Extensibility without forking. EventDetailsRegistry and host-side EventDetailsSection drawer extensions let your team add domain context to the event drawer from the host app. This is the difference between "vendored dependency we patch" and "dependency we configure" — a direct reduction in long-term maintenance ownership.
• Security/authorization posture is now defensible by default. The EmbedOptions::make(sources: []) change (empty lists now deny rather than widen to all sources, same for views/systems) flips embed behavior to deny-by-default. This is a release that likely closes an audit finding; treat it as a security-relevant upgrade, not just a semver major. Invalid/duplicate embed source keys now fail loudly instead of being ignored, moving misconfiguration from silent data exposure to a startup error.
• Demo and scoping assets. The workbench enterprise calendars (tasks, classes, CRM, delivery, overview) are usable as stakeholder demos and as scoping references — they shorten estimation and reduce the "we don't know what this looks like" risk in discovery.
• Onboarding cost estimate. docs/quickstart.md, docs/examples/*, docs/api/public-api.md, and docs/troubleshooting.md materially lower the integration estimate and mean fewer escalations to the vendor/maintainer during rollout.

When to Consider This Package

Adopt when:

• Your product already has Eloquent domain models that carry scheduling semantics (assignments, appointments, shifts, deliveries) and you want them rendered as calendar events without a shadow table.
• You need recurring events tied to real entities rather than a generic event record.
• You are embedding a calendar in a host app (multi-tenant, portal, or customer-facing surface) and want a deny-by-default embed permission model you can defend in a security review.
• You need host-app extension of event detail views without maintaining a fork.
• Your platform is already on (or can move to) PHP 8.3+, Laravel 13, Livewire 4 — this is now a hard floor.

Look elsewhere or defer when:

• You are on Laravel 11/12 or Livewire 3 with no near-term upgrade path. The 2.0.0 requirements bump is an adoption blocker; running the 1.x line means forgoing the Eloquent registry and recurrence work entirely, so plan the platform upgrade first rather than straddling versions.
• You need a scheduling engine (availability computation, conflict resolution, timezone-heavy booking logic, RRULE expansion guarantees) rather than a calendar renderer. This package is a presentation and integration layer over your models; it is not a scheduling service.
• Your calendar surfaces are non-Livewire (API-only, mobile, or server-rendered without Livewire) — the dependency is structural, not incidental.
• You are mid-freeze or in a release-critical window: the EmbedOptions empty-list semantics change is a silent-to-loud behavioral break. Any existing code passing empty arrays to mean "all" will start returning empty calendars. Migration and permission-matrix review must precede the upgrade.

How to Pitch It (Stakeholders)

For executives: This release converts the calendar from a bespoke build into a configuration layer over data we already own. We stop maintaining a parallel event store and a sync path, we add recurring scheduling without a dedicated project, and we gain a deny-by-default embed permission model that strengthens our security posture. The workbench samples give us a credible demo and a tighter scoping baseline, and the new docs cut integration risk. Cost: a platform upgrade to PHP 8.3 / Laravel 13 / Livewire 4 must land first — that is the real budget line, not the package.

For engineering: Major version with two behavioral breaks. (1) EmbedOptions empty sources/views/systems arrays now deny access instead of widening to all — audit every EmbedOptions::make() call site and permission matrix before merge; empty-array-means-everything is now a bug. (2) Invalid or duplicate embed source keys now throw instead of being dropped — expect previously-silent misconfigs to surface as startup failures. Upside is substantial: HasCalendarEvents + Calendar::registerModel() with EloquentEventProvider/EloquentActionHandler, model-level recurrence through EloquentSeries, and EventDetailsRegistry/EventDetailsSection for host-side drawer extension — i.e., we extend without forking. Prerequisites are hard: PHP 8.3+, Laravel 13, Livewire 4. Sequence the platform upgrade, then the package bump, then the embed config audit.