PHP ICS Parser

Because the parser expands (explodes) all recurrence rules into individual event instances, large calendars can consume significant memory. To prevent Fatal error: Allowed memory size exhausted, you can drop events outside a specific window early in the parsing process.

How to use the fuzzy window optimization:

1. Identify the range you need (e.g., yesterday, today, and tomorrow).
2. Set $filterDaysBefore and $filterDaysAfter to a slightly larger window than needed (e.g., +-2d instead of +-1d) to account for imprecise time zone calculations during the early drop phase.
3. Once parsed, call eventsFromRange() with your precise window (e.g., +-1d) to get the exact events.

To install the library, add johngrogg/ics-parser to your composer.json file.

Note: The Composer package owner is johngrogg, not u01jmg3.

To use the latest stable v3 branch, use the ^3 version constraint. If you require new features from the development branch, you can require dev-main.

{ "require": { "johngrogg/ics-parser": "^3" } }

Before installing, ensure your environment meets the following requirements:

• PHP Version: 5.6.40 or higher.
• ICS Files: Must be a valid ICS file (.ics, .ical, or .ifb).
• Time Zone Data: Support for IANA, Unicode CLDR, or Windows Time Zones.

The Event class extends the ICal API and is used to represent individual calendar events. You can instantiate an event with an array of data and use printData() to output the event information within an HTML template.

// Creating an event with data
$event = new Event([
    'summary' => 'Meeting',
    'description' => 'Project discussion',
    'start' => '2023-10-27T10:00:00Z'
]);

// Printing event data in HTML format
echo $event->printData();

Outlook requires a User Agent string to be set in request headers. The parser injects a default User Agent automatically, but you can provide your own using the httpUserAgent argument when instantiating the ICal object.

$ical = new ICal($url, array('httpUserAgent' => 'A Different User Agent'));

Use the initUrl method to load iCalendar data from a remote URL. This method supports HTTP basic authentication and various connection options.

Parameters:

• $url (required): The URL of the iCal feed.
• $username (optional): Username for HTTP basic authentication.
• $password (optional): Password for HTTP basic authentication.
• $userAgent (optional): Custom User Agent string.
• $acceptLanguage (optional): The accepted client language.
• $httpProtocolVersion (optional): The HTTP protocol version.
• $verifySsl (optional): Boolean to control SSL verification (defaults to true).

// Example usage of initUrl
$ical = new ICal();
$ical->initUrl('https://example.com/calendar.ics', 'user', 'pass', 'MyUserAgent', 'en-US', 'HTTP/1.1', true);

After parsing, you can extract events using several methods depending on your needs:

• events(): Returns an array of all Event objects.
• eventsFromRange($rangeStart, $rangeEnd): Returns a sorted array of events within a specific date range. Returns an empty array if no events match.
• eventsFromInterval($interval): Returns a sorted array of events following a given string/interval.
• freeBusyEvents(): Returns an array of arrays containing all free/busy event information.
• hasEvents(): Returns a boolean indicating if the calendar contains any events.

Use these public methods to retrieve top-level calendar information:

• calendarName(): Returns the name of the calendar.
• calendarDescription(): Returns the calendar description.
• calendarTimeZone($ignoreUtc): Returns the calendar time zone. Use the $ignoreUtc parameter to control behavior.