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\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') // Optional
        ->setFilename('myFileName')
        ->setStatus('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)
• setAddress(string $address)
• setDateStart(DateTimeInterface $date, bool $isDateUTC = true, bool $normalizeToUTC = true)
• setDateEnd(DateTimeInterface $date, bool $isDateUTC = true, bool $normalizeToUTC = true)
• setDateStamp(DateTimeInterface $date, bool $isDateUTC = true, bool $normalizeToUTC = true)
• setCalendarType(CalendarTypeEnum $type|null)
• setTransparency(TransparencyEnum $transparency|null)
• setDescription(string $description)
• setSummary(string $summary)
• setOrganizer(string $email)
• setFilename(string $filename)
• setStatus(string $status)
• setSequence(int $sequence)
• setAlarm(bool $enabled)
• setRepeat(bool $enabled)
• setAlarmMinutesBefore(int $minutes)
• setAlarmRepeat(int $repeatCount, ?int $intervalMinutes = null)
• addHeader()
• getICAL(): string

Timezone handling (strict by default)

By default, this library now 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, isDateUTC: true, normalizeToUTC: true)
  • The provided $date is converted to UTC using its own timezone before formatting.
• Opt-out: preserve the literal clock time (no conversion):
  • Pass normalizeToUTC: false and leave isDateUTC: true to emit the time as-is with Z.

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 and add Z (no timezone conversion)
$ical->setDateStart($paris, isDateUTC: true, 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:test
TRANSP:OPAQUE
CALSCALE:GREGORIAN
BEGIN:VEVENT
DTSTART:20141121T150000Z
DTEND:20141121T160000Z
DTSTAMP:20141121T150000Z
SUMMARY:Running
UID:myUid
ORGANIZER:MAILTO:foo@bar.fr
LOCATION:Paris
DESCRIPTION:wonder description
SEQUENCE:2
STATUS:CONFIRMED
END:VEVENT
END:VCALENDAR

Error Handling

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