calendar / icsfile
This simple class generate a .ics file.
Requires
- php: >=8.2.1
Requires (Dev)
- friendsofphp/php-cs-fixer: ^v3.85
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^12.1
- rector/rector: ^2.1
- dev-master
- 9.4.0
- 9.3.0
- 9.2.3
- 9.2.2
- 9.2.1
- 9.2.0
- 9.1.0
- 9.0.0
- 8.0.0
- 7.1.0
- 7.0.0
- 6.3.2
- 6.3.1
- 6.3.0
- 6.2.0
- 6.1.2
- 6.1.1
- 6.1.0
- 6.0.3
- 6.0.2
- 6.0.1
- 6.0.0
- 5.4.2
- 5.4.1
- 5.4.0
- 5.3.0
- 5.2.0
- 5.1.4
- 5.1.3
- 5.1.2
- 5.1.1
- 5.1.0
- 5.0.0
- 4.0.1
- 4.0.0
- 3.2.3
- 3.2.2
- 3.2.1
- 3.2.0
- 3.1.3
- 3.1.2
- 3.1.1
- 3.1.0
- 3.0.0
- 2.3.0
- 2.2.5
- 2.2.4
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.5
- 2.1.4
- 2.1.3
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.0
- 1.1.1
- 1.1.0
- dev-Luc-Sanchez/add-rector-dev-dependancy-1759416547629
This package is auto-updated.
Last update: 2025-10-07 20:04:15 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 leaveisDateUTC: true
to emit the time as-is withZ
.
- Pass
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 simpleREPEAT: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)
setsREPEAT
and, if an interval is set, addsDURATION
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.