calendar/icsfile

This simple class generate a .ics file.

Installs: 113 600

Dependents: 1

Suggesters: 0

Security: 0

pkg:composer/calendar/icsfile

9.4.0 2025-10-02 14:51 UTC

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);

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.