icalendar-generator

Spatie iCalendar Generator is a PHP library that implements the iCalendar specification (RFC 5545, plus extensions from RFC 7986) behind a clean, fluent API. Instead of hand-assembling the fiddly line-folded text format that calendar clients expect, you compose Calendar, Event, Todo, and Alert objects and call get() to produce a valid .ics string.

It handles the parts of the spec that are genuinely hard to get right — automatic VTIMEZONE component generation, recurrence rules, attendees and organizers, attachments, and full-day events — so the calendars you generate load correctly in Apple Calendar, Google Calendar, and Outlook. It works standalone or streamed from a Laravel application.

What You Get

• A fluent builder API for Calendar, Event, Todo, Alert, and Timezone components
• Automatic VTIMEZONE component generation from the timezones on your DateTime objects
• Recurrence rules (RRULE), attendees, organizers, attachments, images, and full-day events
• Spec-compliant, line-folded output that loads correctly in Apple Calendar, Google Calendar, and Outlook

Common Use Cases

• Generating downloadable .ics files for event registrations and bookings
• Serving subscribable calendar feeds with a refresh interval from a web app
• Adding ‘Add to calendar’ functionality to transactional emails and confirmation pages

Under The Hood

Architecture - The library is a clean object graph: user-facing Component subclasses (Calendar, Event, Todo, Alert, Timezone in src/Components/) expose the fluent API and declare their required properties, while serialization is delegated to a two-stage builder pipeline. Each component produces a ComponentPayload that Builders/ComponentBuilder walks recursively, and Builders/PropertyBuilder turns typed Properties/* objects into RFC-correct, \r\n line-folded (chipped) text. Cross-cutting event capabilities are composed via traits in src/Components/Concerns/ (HasAlerts, HasAttendees, HasLocation, HasOrganizer, HasRRule), and timezone components are resolved automatically through the src/Timezones/ layer.

Tech Stack - Pure PHP 8.2+, requiring only ext-mbstring. No runtime framework dependency; Carbon is an optional dev dependency you can use for dates. Dev tooling is modern: Pest 2/3/4 for testing, PHPStan level analysis with a baseline, and PHP-CS-Fixer for styling, all wired through composer scripts and GitHub Actions.

Code Quality - Strong. The tests/ suite spans ~35 test files with snapshot testing (spatie/pest-plugin-snapshots) verifying exact .ics output, plus dedicated datasets and integration tests. Code uses typed properties, PHP 8 constructor promotion, enums for spec vocabularies (ParticipationStatus, EventStatus, Classification, Display, RecurrenceFrequency), and a focused InvalidComponent exception for validation. Naming maps directly to iCalendar concepts.

API Design - Excellent developer experience. Static create() factories plus chainable setters make the common path a one-liner (Calendar::create('...')->event(Event::create('...')->startsAt(...))->get()), while the extensive README documents every property, timezone caveat, and the Laravel streaming integration. Boilerplate is minimal and the API mirrors the mental model of a calendar rather than the raw RFC.