Vobject Laravel Package

Technical Evaluation

Architecture fit. sabre/vobject is a pure, framework-agnostic PHP domain library — no service provider, no facades, no global state, no HTTP layer. For a Laravel codebase this is the ideal shape: it slots in as an infrastructure dependency beneath our own domain code rather than imposing an architecture. It is a format and semantics library (RFC 5545 iCalendar, RFC 6350 vCard, plus iTip scheduling semantics), not an integration library — it will not talk to Google Calendar, Exchange, or CalDAV for us. We consume it at three boundaries: ingest (.ics/.vcf upload, email attachments, webhook payloads), egress (generating invites/exports), and mutation (applying RSVP, cancellation, attendee, and recurrence edits). Anything beyond that is our build.

Integration feasibility. Low friction. composer require sabre/vobject "^4.0"; Composer autoloading is all that is required, and it coexists cleanly with Laravel's HTTP, queue, storage, and notification stack. The realistic work is not the install, it is the adapter: our own CalendarService/VCardService wrapping Reader::read(), VCalendar::serialize(), and the ITip\Broker so the library's API surface does not leak into controllers and jobs. The README's PHP 5.5 floor is stale documentation — release notes confirm PHP 8.4 support in 4.5.6, so the current 4.5/4.6 line is compatible with modern Laravel runtime requirements.

Technical risk.

• Metadata integrity (diligence blocker). "1 star / 0 dependents" for the reference implementation of PHP iCalendar/vCard handling is almost certainly a capture artifact — the fruux/sabre-vobject URL is a historical redirect to the maintained sabre-io/vobject. Before this appears in any decision record, confirm the canonical Packagist package (sabre/vobject), install counts, and downstream consumers. Do not let a bad signal suppress an otherwise sound choice, and do not let it be discovered later by someone else.
• Recurrence correctness is the historical fault line. The changelog is a long tail of RRuleIterator fixes: infinite loops (#443, #564, #567, #383), BYDAY handling, BY SETPOS, yearly/BYYEARDAY, RDATE range checks, DST jumps. This is the hardest part of the spec and the part most likely to produce a customer-visible wrong occurrence. Treat recurrence expansion as a tested seam, not a utility call.
• Behavioral drift in minor releases. 4.6.0 changed FindFromTimezoneMap::find from throwing to returning null in a minor version. That is a silent-breakage pattern for callers with try/catch. Pin a minor (~4.5.x) or ~4.6.x deliberately, and add a timezone-resolution test.
• Untrusted-input exposure. Parsing arbitrary .ics/.vcf from uploads or inbound mail means attacker-controlled structure, unbounded recurrence expansion, large payloads, and malformed lines. The parser is forgiving-by-design in places, which is good for UX and bad for resource control. Bound input size, cap expansion windows, run in workers with time/memory limits.
• Maintenance concentration. Single-vendor origin (fruux) with community maintenance. Healthy release cadence through 2026, but bus factor and SLA are not enterprise-grade unless we buy commercial support.
• License. BSD-3-Clause — permissive, attribution-only, no copyleft contamination of our application code. Clean pass for commercial distribution.

Key questions.

1. Which of the three use cases is actually on the roadmap — iCalendar, vCard, or both? (vCard 2.1 is explicitly out of scope; some CRM/legacy sources still emit it, which would force a pre-normalization step.)
2. Do we need server-side iTip (Broker: invites, replies, cancellations, SEQUENCE/DTSTAMP handling), or is one-way export sufficient? iTip roughly doubles the complexity and the test surface.
3. Is CalDAV sync (bidirectional, server-of-record) in scope? If yes, scope sabre/dav now — it is a different commitment than this library.
4. What is our PHP version floor and upgrade cadence? It determines whether we can ride the current 4.x line or must support the 3.x branch.
5. Who owns the adapter layer and the recurrence test corpus? This is a named person, not a team.

Integration Approach

Stack fit. Native. No Laravel package, container bindings, or config publishing required; we should not seek a third-party Laravel wrapper — the ecosystem of thin wrappers around this library is small and adds a maintenance hop without adding correctness. Recommended shape:

• composer require sabre/vobject:~4.5 (or ~4.6 once the timezone-null change is validated) — explicit, bounded, not ^4.0.
• app/Calendar/ (or app/Contacts/) domain layer exposing our own DTOs, with the library used only inside that layer.
• Parsing/serialization behind an interface so it is mockable and replaceable.
• Laravel-native plumbing around it: Storage for raw artifacts, queued jobs for parse/expand/generate, Notification/Mail to deliver invites, Form Requests + validation for upload guards.
• Config for policy, not for the library: max file size, max expansion horizon (e.g. 2 years / 750 occurrences), allowed component types.

Migration path. Nothing to migrate — greenfield dependency. The migration is of responsibility: move any existing ad-hoc .ics string manipulation, str_replace-based invite generation, or bespoke RRULE arithmetic into the adapter, and delete it. If a legacy integration exists, run it in parallel on a shadow dataset and diff outputs before cutover.

Compatibility.

• PHP 8.1–8.4 clean on 4.5.6+; verify against our pinned Laravel/PHP matrix in CI.
• sabre/xml is an optional-ish dependency path (4.5.3 relaxed it to allow v2/v3/v4); if we also use sabre/dav later, watch for the return-type declarations (xmlSerialize(): void, xmlDeserialize(): array) noted in 4.5.3 if we subclass.
• Timezone truth: the library carries its own timezone map and exchange-timezone aliases, which can diverge from config('app.timezone') and PHP's DateTimeZone. Store UTC, render in the user's zone, and keep one module responsible for conversion.
• vCard 3.0/4.0 supported; 2.1 not. iCalendar 2.0 (RFC 5545) supported.

Sequencing.

1. Spike (1–2 days). Parse and round-trip a real corpus: Google export, Outlook export, Apple export, a recurring event across a DST boundary, a malformed file, a 5k-event file. Output: measured latency, memory, and a list of spec gaps.
2. Adapter + contract tests. Land the wrapper, the DTOs, and a golden-file test suite checked into the repo. Gate: recurrence fixtures pass.
3. Read path. Import/ingest with validation, size caps, and error surfacing to users. Lowest risk, highest immediate value.
4. Write path. Export and generation, including UID, DTSTAMP (must be UTC), SEQUENCE discipline.
5. iTip (only if Q2 is yes). Invite/reply/cancel via Broker; this is the phase that needs the most QA and the most product spec (who is organizer, how do we handle attendee-added-by-forward).
6. Recurrence expansion at scale. Move to queued, chunked expansion; cache next-occurrence rather than materializing full series.
7. CalDAV (separate decision, separate ticket).

Operational Impact

Maintenance. Upstream is actively maintained with a steady, issue-linked changelog (through 4.6.0) and modern-PHP CI coverage — better than the star count implies. Our recurring cost is small but permanent: version bumps, re-running the golden-file corpus, and watching for behavior changes in minor releases. Budget roughly a few days per quarter, plus one focused pass per PHP/Laravel upgrade. The genuinely expensive maintenance is our adapter and fixture corpus, not the dependency.

Support. Upstream support is a Google Group mailing list plus commercial services from fruux. There is no paid SLA in our contract unless we buy one. Practical implication: our on-call runbook must assume we debug our own calendar logic; the library is not a support channel we can escalate a production incident into. Where a spec edge case bites a customer, we own the workaround.

Scaling. The library is CPU-bound and stateless — it scales the same way any pure PHP code does, by adding workers. The two hot spots are (a) recurrence expansion and (b) serialization of large calendars; both received targeted performance work upstream (4.1.4–4.1.6) but neither is free. Guidance: never expand recurrences in a request cycle; cap horizons rather than offering "all occurrences"; paginate imports; avoid re-serializing the whole calendar to change one property on a very large series. For a typical SaaS volume (thousands of calendars, tens of thousands of events) this is comfortably a queue-worker problem, not an infrastructure problem.

Failure modes to instrument and alert on.

• ParseException / InvalidDataException spikes after a client releases a new export format — the leading indicator of an interop regression.
• Silent recurrence mis-expansion — no exception, wrong date. Only caught by golden-file tests and by reconciling "events shown" against "events expected." Highest-severity, lowest-detectability.
• Infinite-loop / timeout on pathological RRULE input (historically the top defect class). Enforce hard timeouts and reject rather than hang.
• Timezone drift — TZID not found returning null (new 4.6.0 behavior), deprecated zone aliases updated underneath us, DST transitions on recurring events. Manifests as off-by-one-hour meeting notices, which customers notice immediately.
• Memory exhaustion on oversized payloads; enforce a size ceiling before Reader::read().
• Duplicate or missing iTip messages — SEQUENCE/DTSTAMP/significant-change detection errors produce either invite spam or invisible updates to attendees. Both are trust-damaging; test explicitly.
• Organizer/attendee identity confusion on forwarded invites, producing replies to the wrong party.

Ramp-up. Shallow learning curve for parse/serialize — a mid-level Laravel developer is productive in a day, because the API is small and documented (sabre.io/vobject/vcard/, /icalendar/). The steep part is semantics, not syntax: RFC 5545 recurrence and timezone rules, and iTip's state machine around SEQUENCE, METHOD, cancellations, and exceptions. Plan for one engineer to become the named calendar-semantics owner, give them the fixture corpus as their artifact, and set expectations that recurrence bugs are a class of bug we will keep fixing rather than a task we finish. Do not distribute iTip ownership across the team.

Bottom line for the roadmap. The dependency itself is a low-risk, high-leverage buy: it removes months of RFC compliance work and is properly licensed. The decision to defend is not "should we use this library" but "which of import/export, iTip, and CalDAV are in scope" — because the first is a week, the second is a quarter, and the third is a different product. Approve the dependency and Phase 3; gate Phases 5 and 7 on explicit roadmap commitment.