README

This library allows you to easily generate iCalendar (.ics) files in PHP, following the iCalendar (RFC 5545) specification.

Installation

Make sure you have installed the dependencies via Composer:

composer install

Include the Composer autoloader in your script:

require_once 'vendor/autoload.php';

Usage

Below is a basic example of creating an iCalendar event:

<?php

require_once 'vendor/autoload.php';

use Ical\Ical;
use Ical\Enum\CalendarTypeEnum;
use Ical\Enum\StatusEnum;
use Ical\Enum\TransparencyEnum;
use Ical\Exceptions\IcalendarException;

try {
    $ical = (new Ical())
        ->setName('test')
        ->setAddress('Paris')
        ->setDateStart(new \DateTimeImmutable('2014-11-21 15:00:00', new \DateTimeZone('UTC')))
        ->setDateEnd(new \DateTimeImmutable('2014-11-21 16:00:00', new \DateTimeZone('UTC')))
        ->setDateStamp(new \DateTimeImmutable('2014-11-21 15:00:00', new \DateTimeZone('UTC')))
        ->setCalendarType(CalendarTypeEnum::GREGORIAN)
        ->setTransparency(TransparencyEnum::OPAQUE) // Optional
        ->setDescription('wonder description')
        ->setSummary('Running')
        ->setOrganizer('foo@bar.fr', 'Foo Bar') // Optional — second parameter sets CN (display name)
        ->setFilename('myFileName')
        ->setStatus(StatusEnum::CONFIRMED) // Optional
        ->setSequence(2); // Number of updates (default is 1, optional)

    $ical->addHeader();

    echo $ical->getICAL();

} catch (IcalendarException $exc) {
    echo $exc->getMessage();
}

Methods (overview)

• setName(string $name)
• setProdId(string $organisation, string $product, string $language = 'EN')
• setAddress(string $address)
• setDateStart(DateTimeInterface $date, bool $normalizeToUTC = true)
• setDateEnd(DateTimeInterface $date, bool $normalizeToUTC = true)
• setDateStamp(DateTimeInterface $date, bool $normalizeToUTC = true)
• setCalendarType(?CalendarTypeEnum $type)
• setTransparency(?TransparencyEnum $transparency)
• setDescription(string $description)
• setSummary(string $summary)
• setOrganizer(string $email, ?string $name = null)
• setFilename(string $filename)
• setStatus(StatusEnum $status)
• setSequence(int $sequence)
• setTimezoneICal(string $timezone)
• setAlarm(bool $enabled)
• setRepeat(bool $enabled)
• setAlarmMinutesBefore(int $minutes)
• setAlarmRepeat(int $repeatCount, ?int $intervalMinutes = null)
• setIncludeVtimezone(bool $include)
• addHeader()
• getICAL(?string $uid = null): string

PRODID (identifiant du calendrier)

Le champ PRODID identifie l'application qui a généré le fichier. La norme iCalendar (RFC 5545) impose le format :

-//Organisation//Produit//LANG

Utilisez setProdId() pour générer un PRODID conforme. Si vous ne l'appelez pas, le champ name est utilisé en fallback (comportement d'avant, rétrocompatible).

$ical->setProdId('Bob Morane', 'Conference Calendar', 'FR');
// → PRODID:-//Bob Morane//Conference Calendar//FR

$ical->setProdId('My Company', 'Booking App');
// → PRODID:-//My Company//Booking App//EN  (langue EN par défaut)

ORGANIZER (organisateur de l'événement)

Le champ ORGANIZER accepte un paramètre CN (Common Name) optionnel pour afficher un nom lisible. Certains clients comme Google Calendar le requièrent pour accepter les modifications.

// Avec nom d'affichage (recommandé)
$ical->setOrganizer('ariane@jose-sanchez.fr', 'Ariane');
// → ORGANIZER;CN=Ariane:MAILTO:ariane@jose-sanchez.fr

// Sans nom (rétrocompatible)
$ical->setOrganizer('ariane@jose-sanchez.fr');
// → ORGANIZER:MAILTO:ariane@jose-sanchez.fr

Timezone handling (strict by default)

By default, this library normalizes all provided timestamps to UTC (strict mode) and emits them with a trailing Z. This ensures consistent behavior regardless of the host/server timezone.

• Strict default (real UTC normalization):
  • setDateStart($date) — the provided $date is converted to UTC using its own timezone before formatting.
• Opt-out: preserve the literal clock time (no UTC conversion):
  • Pass normalizeToUTC: false to emit the time as-is without conversion.

Examples:

$paris = new \DateTimeImmutable('2025-10-02 10:00:00', new \DateTimeZone('Europe/Paris'));

// 1) Strict (default): convert to real UTC (10:00 Paris -> 08:00Z depending on DST)
$ical->setDateStart($paris); // outputs DTSTART:20251002T080000Z

// 2) Opt-out: keep the provided clock time as-is (no timezone conversion)
$ical->setDateStart($paris, normalizeToUTC: false); // outputs DTSTART:20251002T100000Z

Tip: For fully deterministic tests, build your DateTime with an explicit timezone (e.g., new DateTimeZone('UTC')).

Alarms (VALARM)

Two usage styles are supported and backward compatible:

• Backward-compatible flags:
  • setAlarm(true) enables a default reminder of 15 minutes before the event.
  • setRepeat(true) adds a simple REPEAT:1.
• Fine-grained configuration:
  • setAlarmMinutesBefore(int $minutes) sets the trigger offset before the event start, and auto-enables the alarm.
  • setAlarmRepeat(int $repeatCount, ?int $intervalMinutes = null) sets REPEAT and, if an interval is set, adds DURATION accordingly.

Examples:

// Simple: 15 minutes before, one repeat
$ical->setAlarm(true)->setRepeat(true);

// Custom: 30 minutes before, repeat 3 times every 10 minutes
$ical->setAlarmMinutesBefore(30)->setAlarmRepeat(3, 10);

VTIMEZONE management

By default, the generated ICAL includes a VTIMEZONE section (for example Europe/Paris). This is recommended for compatibility with most calendar clients.

If you want to disable the VTIMEZONE section (for example for UTC-only events or specific needs), you can do so:

$ical = new Ical();
$ical->setIncludeVtimezone(false); // VTIMEZONE will not be included

To check the default behavior:

• VTIMEZONE is present unless you call $ical->setIncludeVtimezone(false).
• You can change the timezone with $ical->setTimezoneICal('Europe/Berlin').

Example with VTIMEZONE disabled:

$ical = new Ical();
$ical->setName('test')
    ->setDateStart(new \DateTimeImmutable('2025-10-10T10:00:00Z'))
    ->setDateEnd(new \DateTimeImmutable('2025-10-10T12:00:00Z'))
    ->setIncludeVtimezone(false);
$icalString = $ical->getICAL();

See tests/IcalTest.php for unit tests covering both cases.

Example Output

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Bob Morane//Conference Calendar//FR
CALSCALE:GREGORIAN
BEGIN:VEVENT
DTSTART:20141121T150000Z
DTEND:20141121T160000Z
DTSTAMP:20141121T150000Z
SUMMARY:Running
UID:myUid
ORGANIZER;CN=Foo Bar:MAILTO:foo@bar.fr
LOCATION:Paris
DESCRIPTION:wonder description
SEQUENCE:2
STATUS:CONFIRMED
TRANSP:OPAQUE
END:VEVENT
END:VCALENDAR

Status values (StatusEnum)

The setStatus() method accepts a StatusEnum case:

• StatusEnum::CONFIRMED
• StatusEnum::TENTATIVE
• StatusEnum::CANCELLED

use Ical\Enum\StatusEnum;

$ical->setStatus(StatusEnum::CONFIRMED);

Error Handling

All exceptions are instances of IcalendarException. Use try/catch to handle errors when generating the calendar.