eluceo — iCal 2

The eluceo/ical package allows you to generate iCalendar (.ics) files following the RFC 5545 specification. It uses a two-layer architecture to decouple event data from the file format:

1. Domain Layer (Eluceo\iCal\Domain): Use these classes to store calendar information (events, calendars, dates) in simple PHP objects. This layer requires no deep knowledge of the iCalendar specification.
2. Presentation Layer (Eluceo\iCal\Presentation): Use these classes to transform your domain objects into the actual iCalendar string representation.

To generate a file, you define your events and calendars using domain entities, then use a CalendarFactory to convert the calendar into a string component.

<?php

use Eluceo\iCal\Domain\Entity\Calendar;
use Eluceo\iCal\Domain\Entity\Event;
use Eluceo\iCal\Domain\ValueObject\Date;
use Eluceo\iCal\Domain\ValueObject\SingleDay;
use Eluceo\iCal\Presentation\Factory\CalendarFactory;

// 1. Create Event domain entity
$event = new Event();
$event
    ->setSummary('Christmas Eve')
    ->setOccurrence(
        new SingleDay(
            new Date(DateTimeImmutable::createFromFormat('Y-m-d', '2030-12-24'))
        )
    );

// 2. Create Calendar domain entity
$calendar = new Calendar([$event]);

// 3. Transform domain entity into an iCalendar component
$componentFactory = new CalendarFactory();
$calendarComponent = $componentFactory->createCalendar($calendar);

// 4. Set HTTP headers
header('Content-Type: text/calendar; charset=utf-8');
header('Content-Disposition: attachment; filename="cal.ics"');

// 5. Output
echo $calendarComponent;

The setOccurrence() method defines when an event takes place. There are three supported types of occurrences:

1. SingleDay: The event takes place all day on a specific date.
2. MultiDay: The event spans multiple consecutive days (inclusive of start and end dates).
3. TimeSpan: The event has a specific start and end time.

Use the appropriate ValueObject from \Eluceo\iCal\Domain\ValueObject to define the timing.

use Eluceo\iCal\Domain\Entity\Event;

// 1. Single Day
use Eluceo\iCal\Domain\ValueObject\SingleDay;
use Eluceo\iCal\Domain\ValueObject\Date;
$date = new Date(DateTimeImmutable::createFromFormat('Y-m-d', '2019-12-24'));
$event->setOccurrence(new SingleDay($date));

// 2. Multi Day
use Eluceo\iCal\Domain\ValueObject\MultiDay;
$firstDay = new Date(DateTimeImmutable::createFromFormat('Y-m-d', '2019-12-24'));
$lastDay = new Date(DateTimeImmutable::createFromFormat('Y-m-d', '2019-12-26'));
$event->setOccurrence(new MultiDay($firstDay, $lastDay));

// 3. TimeSpan
use Eluceo\iCal\Domain\ValueObject\TimeSpan;
use Eluceo\iCal\Domain\ValueObject\DateTime;
$start = new DateTime(DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2020-01-03 13:00:00'), false);
$end = new DateTime(DateTimeImmutable::createFromFormat('Y-m-d H:i:s', '2020-01-03 14:00:00'), false);
$event->setOccurrence(new TimeSpan($start, $end));

This workflow demonstrates the minimum steps required to generate an iCalendar file containing a single empty event.

1. Create an event domain entity: Instantiate \Eluceo\iCal\Domain\Entity\Event.
2. Create a calendar domain entity: Instantiate \Eluceo\iCal\Domain\Entity\Calendar and pass the event(s) in the constructor.
3. Transform to presentation: Use \Eluceo\iCal\Presentation\Factory\CalendarFactory to create a calendar component.
4. Output: Cast the component to a string to save to a file or echo via HTTP.

// 1. Create an event domain entity
$event = new \Eluceo\iCal\Domain\Entity\Event();

// 2. Create a calendar domain entity
$calendar = new \Eluceo\iCal\Domain\Entity\Calendar([$event]);

// 3. Transform calendar domain object into a presentation object
$iCalendarComponent = (new \Eluceo\iCal\Presentation\Factory\CalendarFactory())->createCalendar($calendar);

// 4. a) Save to file
file_put_contents('calendar.ics', (string) $iCalendarComponent);

// 4. b) Send via HTTP
header('Content-Type: text/calendar; charset=utf-8');
header('Content-Disposition: attachment; filename="cal.ics"');
echo $iCalendarComponent;

To add non-standard properties (e.g., X-CUSTOM: value) to an iCal file, you must extend the domain entity to store the data and extend the factory to include the property in the presentation component. This process involves three main steps: extending \Eluceo\iCal\Domain\Entity\Event, extending \Eluceo\iCal\Presentation\Factory\EventFactory, and passing your custom factory to the CalendarFactory.

<?php
// 1. Create custom entity
class CustomEvent extends \Eluceo\iCal\Domain\Entity\Event {
    private string $myCustomProperty = 'foo bar baz!';
    public function getMyCustomProperty(): string { return $this->myCustomProperty; }
}

// 2. Create custom factory
class CustomEventFactory extends \Eluceo\iCal\Presentation\Factory\EventFactory {
    public function createComponent(\Eluceo\iCal\Domain\Entity\Event $event): \Eluceo\iCal\Presentation\Component {
        $component = parent::createComponent($event);
        if ($event instanceof CustomEvent) {
            $component = $component->withProperty(
                new \Eluceo\iCal\Presentation\Component\Property(
                    'X-CUSTOM',
                    new \Eluceo\iCal\Presentation\Component\Property\Value\TextValue($event->getMyCustomProperty())
                )
            );
        }
        return $component;
    }
}

// 3. Plug it together
$event = new CustomEvent();
$event->setSummary('This is a test event');
$calendar = new \Eluceo\iCal\Domain\Entity\Calendar([$event]);

$calendarComponentFactory = new \Eluceo\iCal\Presentation\Factory\CalendarFactory(new CustomEventFactory());
$calendarComponent = $calendarComponentFactory->createCalendar($calendar);

echo $calendarComponent;

A Calendar is a collection of Event entities that can be represented as an .ical file. You can instantiate a calendar and populate it with events using three different methods:

1. Via Constructor: Pass an array of Event objects directly to the Calendar constructor.
2. Via addEvent() method: Create an empty Calendar and chain calls to addEvent() for each new Event.
3. Via Generator: Pass a PHP Generator that yields Event objects to the Calendar constructor, which is useful for memory-efficient processing of large numbers of events.

use Eluceo\ iCal\u0020Domain\u0020Entity\u0020Calendar;
use Eluceo\u0020iCal\u0020Domain\u0020Entity\u0020Event;

// Method 1: Constructor with array
$events = [
    new Event(),
    new Event(),
];
$calendar = new Calendar($events);

// Method 2: addEvent method
$calendar = new Calendar();
$calendar
    ->addEvent(new Event())
    ->addEvent(new Event());

// Method 3: Using a Generator
$eventGenerator = function(): Generator {
    yield new Event();
    yield new Event();
};
$calendar = new Calendar($eventGenerator());