yohang/calendr
Calendr is an object-oriented PHP calendar library for creating, managing, and rendering calendars and events. It supports recurring events, multiple calendars, and flexible output via renderers, making it easy to integrate scheduling into PHP applications.
Architecture fit. Calendr is a framework-agnostic, object-oriented domain library rather than a Laravel package. That is the right shape for us: it belongs in the domain layer, not the infrastructure layer, and can be consumed through a thin application-level port (CalendarService interface) that keeps the rest of the codebase insulated from the dependency. PHP 8.2+ is consistent with our Laravel 11/12 baseline, and the use of modern language features (enums, readonly properties, immutable value objects) suggests a smaller, cleaner API surface than the legacy DateTime-mutating libraries. The main fit question is whether its date/time primitives interop cleanly with Carbon, because everything else in our stack — Eloquent casts, Blade, scheduled jobs — speaks Carbon.
Integration feasibility. Composer-installable with a typical ServiceProvider + optional facade wrapper; expected effort is low (1–3 days for a working adapter, not weeks). The real work is not wiring but translation: mapping Eloquent models to the library's value objects, defining casts, and normalizing timezone handling at the boundary. No framework coupling means no version-lock risk against Laravel upgrades, which is the usual failure point for calendar packages.
Technical risk. Three concrete concerns:
Repository: unknown. We cannot currently verify source, CI, security policy, or release signers. That is a supply-chain blocker until independently confirmed — treat it as a gate, not a footnote.Key questions to close before commitment: Does it implement RFC 5545 recurrence, or only simple intervals? Is the recurrence expansion bounded (infinite-series guard)? Are value objects immutable and serializable? What is the timezone model — stored UTC with zone rendering, or floating local time? Is the public API semver-stable, and is there a documented extension point for custom calendars/holiday providers? Can we get a security contact and a reproducible build?
Stack fit. Good, with the caveat that fit is achieved by us writing the adapter, not by the library providing one. Laravel's scheduler, queued jobs, and Blade all remain untouched; Calendr sits behind a single application service. If the library's model proves insufficient, we swap the implementation behind that interface without touching call sites — this is the primary reason to adopt it through a port rather than calling it directly from controllers and models.
Migration path. Do not migrate existing date logic wholesale. Sequence instead: (1) inventory current calendar/date-handling code and classify it as rendering, availability calculation, recurrence, or persistence; (2) define the port interface against our own domain terms; (3) implement the port with Calendr for the read-only, lowest-risk use cases first (rendering grids, business-day math); (4) leave writes and persistence on existing Eloquent/Carbon code until the read path is proven; (5) retire the old path module by module.
Compatibility. Two seams need explicit design. First, a bidirectional bridge between DateTimeImmutable/Carbon and Calendr's value objects, plus custom Eloquent casts so persisted events round-trip without drift. Second, an API serialization contract (JSON:API resources or DTOs) that pins date format and offset handling — this is where most integration regressions appear. Timezone configuration should be centralized in one place (config/app.php plus a single normalization helper), never scattered.
Sequencing. Spike (2–3 days) covering recurrence + DST + serialization → adapter and interface → casts and persistence tests → recurrence expansion with caching → iCalendar import/export → holiday/working-day provider → UI components. Gate the go/no-go decision at the end of the spike, not at the end of the project.
Maintenance. MIT license is permissive and low-risk. We must own the dependency: pin via lockfile, subscribe to release notifications, and maintain fork readiness (the library is small enough that a fork is a viable contingency at roughly a few days of effort). Recent releases are a positive signal but the cadence should be monitored quarterly.
Support. No commercial support; community issues only, likely with variable response time. Budget internal expertise — one engineer should be designated owner and should read the recurrence and timezone code, not just the README. That is the real total cost of ownership here, and it dwarfs the license cost of zero.
Scaling. The performance hotspot is recurrence expansion: materializing occurrences over a large window is CPU- and memory-bound and is the classic place this class of library degrades. Mitigate by precomputing and caching expanded ranges (e.g., a materialized occurrences table plus a cache keyed on calendar + range + version), enforcing a maximum expansion horizon, and never expanding inside a request path for unbounded series.
Failure modes to instrument. Timezone/DST misinterpretation producing off-by-one-hour shifts; ambiguous local times resolving inconsistently across environments; stale holiday data silently affecting payroll- or SLA-adjacent calculations; malformed or hostile iCalendar input; unbounded recurrence causing request timeouts or worker memory exhaustion; silent date drift on serialize/deserialize. Each warrants an automated test plus an alert where the output feeds billing or scheduling.
Ramp-up. Small API surface; a mid-level Laravel engineer should be productive in one to two days. The genuine learning curve is domain modeling of recurrence and timezone semantics, which is transferable knowledge regardless of whether we keep the library. Recommend a two-week timeboxed evaluation with a written go/no-go at the end, contingent on resolving the repository provenance question first.
How can I help you explore Laravel packages today?