Ical Laravel Package

Product Decisions This Supports

Build vs. buy — calendar output is a "buy." Any feature that emails a .ics file, serves a "subscribe to this calendar" URL, or adds an "Add to calendar" action needs RFC 5545-compliant output: line folding at 75 octets, text escaping, VFREQUENCY/RRULE syntax, VTIMEZONE blocks, and DST-correct DTSTART/DTEND handling. This package abstracts all of it behind domain objects. Hand-rolling it is a 2–4 week build plus a permanent tail of "event appears an hour off in Outlook" tickets. MIT license, no procurement friction, no legal review.

Feature bets this unlocks or de-risks:

• Transactional calendar attachments — booking confirmations, appointment reminders, delivery windows, trial-expiry notices. The CalendarFactory output can be dropped straight into a Laravel Mailable attachment with Content-Type: text/calendar.
• Subscription feeds (ICS URLs) — roster/shift schedules, course timetables, release calendars, maintenance windows. setPublishedTTL() (X-PUBLISHED-TTL) lets you steer how aggressively Outlook/Apple Calendar re-poll, which is a real load-management lever on your own endpoint.
• "Add to calendar" growth surface — Google/Outlook web-link vs. downloadable .ics is a standard growth experiment; this package makes the download half a one-day task, not a sprint.
• Event richness as a product differentiator — ORGANIZER, ATTENDEE, STATUS (CONFIRMED/TENTATIVE/CANCELLED), CATEGORIES, URL, LAST-MODIFIED, GEO, ATTACH. Cancellation/status semantics are what make "your appointment was cancelled" actually propagate into the user's calendar rather than leaving a zombie event.
• Recurrence as a roadmap enabler — weekly recurring bookings, series schedules, BYSETPOS (e.g. "last weekday of the month"). Doing recurrence in-house is where naive implementations quietly break for months.

Roadmap / sequencing signal: the domain-vs-presentation split in v2 is the important architectural fact. Domain objects (Event, Calendar, SingleDay, Date, DateTime) describe what happened; Presentation\Factory\CalendarFactory decides how it's serialized. That means "generate an ICS" and "render the same schedule as a web page / PDF / push payload" can share one domain model. It also means you can unit-test event construction without touching string output — cheap coverage for QA.

Where it should not change the roadmap: it is a writer only. It will not read, parse, or ingest .ics. If the roadmap contains inbound calendar sync, CalDAV/CardDAV, two-way Google Calendar integration, or "import from Outlook," this package is at most 20% of that story and should not be scoped as if it's the solution.

Planning note for engineering capacity: this is a thin, boring dependency — days, not weeks. The actual work in any calendar feature is timezone correctness in your data model, the delivery path (attachment vs. hosted URL vs. both), and cache/ETag handling on the feed endpoint. Budget accordingly; don't let the calendar ticket get sized by the library.

When to Consider This Package

Adopt when all of these hold:

• PHP/Laravel stack and outbound-only calendar needs. Generating .ics for download, email attachment, or a hosted subscription URL.
• You need RFC-adjacent correctness without owning it — timezones, DST, all-day event semantics, line folding, escaping. The changelog shows these being actively fixed over a decade (TZOFFSETTO/-0000, all-day end-date rollover, \n escaping regression in 2.14, UTC formatting in 2.10). That institutional memory is the thing you'd otherwise rediscover in production.
• Recurrence is on the near-term roadmap, even if v1 of the feature is single events. Retrofitting RRULE later is the expensive path.
• You can test-drive it cheaply. It is a pure library — no service, no schema, no migration, no vendor account. Two days of spike gets you a decision.
• License/legal needs zero friction. MIT.

Look elsewhere (or scope down) when:

• You need to read or parse calendars. Write-only; go find a parser or a CalDAV client.
• You need two-way sync, webhooks, or hosted calendar infrastructure (Google Calendar API, Microsoft Graph, Nylas, Cronofy). Those solve a different problem — this package just produces the file.
• Calendar generation belongs in the browser. For "add to calendar" on a marketing page, client-side JS may beat a server round-trip.
• You need vendor SLAs or commercial support. Single-maintainer OSS; see risk below.
• You need full RRULE expansion logic (i.e. "give me every occurrence between date X and Y"). This package emits the rule; it does not evaluate it. Expand recurrence on your side or via a dedicated library.

Two adoption risks a PM should price in — both are schedule risks, not capability risks:

1. Aggressive PHP-version support window. The support matrix is narrow and moves fast: >=2.16 targets PHP 8.4–8.5 and removed 8.3; 2.15 covered 8.3–8.4; <2.14 covers 7.4–8.3. If a Laravel LTS on PHP 8.2/8.3 is in the estate, you must pin eluceo/ical in Composer and treat the PHP upgrade and the library upgrade as one coupled workstream. Put a standing line item in the platform-upgrade checklist so this doesn't ambush a release.
2. Single-maintainer bus factor, ~1.2k stars. Small by absolute numbers, but this is a niche, and "dependents: 0" in the metadata is almost certainly a registry artifact rather than a real signal — the package has shipped since 2012 with a maintained changelog, CI, Psalm, and Infection mutation-testing badges. Mitigation is cheap: it's a pure, side-effect-free library with a clean domain boundary, so a fork-and-own fallback is realistic. Note it as a risk, not a blocker.

Version decision to make explicitly: v2 is a complete rewrite and not compatible with 0.*. Greenfield projects should start on v2. If any internal package or legacy service is on 0.x, treat the migration as its own scoped task using the published upgrade guide — do not assume a drop-in bump.

How to Pitch It (Stakeholders)

For executives — one paragraph: Calendar files are a small feature with a disproportionate correctness bar: an event that lands an hour wrong, or a cancelled meeting that stays on someone's calendar, damages trust in the product more than the feature ever earned. eluceo/ical is a free (MIT), ten-year-old PHP library that gets those details right — timezones, all-day events, recurrence, cancellation status — and lets us ship booking confirmations and subscription calendar feeds in days instead of weeks. It is a write-only library: it produces calendar files and does not read them, so it is not a path to two-way Google/Outlook sync. The decision is low-cost and reversible; the main thing to manage is a tight PHP-version support window, which we handle by pinning the version and bundling its upgrade into our existing PHP upgrade cycle.

For engineering — the short version: add eluceo/ical via Composer. Build Domain\Entity\Event objects (setSummary, setDescription, setOccurrence, setOrganizer, setStatus, addRecurrenceRule), collect them in Domain\Entity\Calendar, then serialize with Presentation\Factory\CalendarFactory::createCalendar(). Cast to string; file_put_contents for a feed, or attach to a Laravel Mailable / return with Content-Type: text/calendar; charset=utf-8 and a Content-Disposition: attachment; filename="cal.ics" header. No service provider, no config, no facade needed — a thin wrapper class is enough. It's framework-agnostic and stateless. Pin the version against your PHP runtime (2.16 requires PHP 8.4–8.5 and drops 8.3; use 2.15 if you're on 8.3). Do not use it for parsing or CalDAV.

Success metrics to instrument: click-through on "add to calendar," attachment open/add rate on confirmation emails, subscription-feed adoption (unique authenticated ICS URLs fetched per week), and — the real one — a decline in support tickets matching "wrong time," "wrong day," or "event won't update." If those tickets don't fall after launch, the problem is almost certainly in our timezone data or feed caching, not in this library.