Parser for iCalendar Events • written in PHP 5 (≥ 5.3.0)
Clone or download
u01jmg3 Merge pull request #191 from marcelstoer/master
Add ignores for IntelliJ IDEA
Latest commit fcd294f Nov 6, 2018

README.md

PHP ICS Parser

Latest Stable Release Total Downloads


Installation

Requirements

  • PHP 5 (≥ 5.3.0)
  • Valid ICS (.ics, .ical, .ifb) file
  • IANA, Unicode CLDR or Windows Time Zones
    • Windows will need the $replaceWindowsTimeZoneIds = true configuration

Setup

  • Install Composer
    • Add the following dependency to composer.json
      • ⚠️ Note with Composer the owner is johngrogg and not u01jmg3
    • To access the latest stable branch (v2) use the following
      • To access new features you can require dev-master

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

How to use

How to instantiate the Parser

What will the parser return?

  • Each key/value pair from the iCal file will be parsed creating an associative array for both the calendar and every event it contains.

  • Also injected will be content under dtstart_tz and dtend_tz for accessing start and end dates with time zone data applied.

  • Where possible DateTime objects are used and returned.

    // Dump the whole calendar
    var_dump($ical->cal);
    
    // Dump every event
    var_dump($ical->events());
  • Also included are special {property}_array arrays which further resolve the contents of a key/value pair.

    // Dump a parsed event's start date
    var_dump($event->dtstart_array);
    
    // array (size=4)
    //   0 =>
    //     array (size=1)
    //       'TZID' => string 'America/Detroit' (length=15)
    //   1 => string '20160409T090000' (length=15)
    //   2 => int 1460192400
    //   3 => string 'TZID=America/Detroit:20160409T090000' (length=36)

API

ICal API

Variables

Name Configurable Default Value Description
$alarmCount ✖️ N/A Tracks the number of alarms in the current iCal feed
$cal ✖️ N/A The parsed calendar
$defaultSpan ☑️ 2 The value in years to use for indefinite, recurring events
$defaultTimeZone ☑️ System default Enables customisation of the default time zone
$defaultWeekStart ☑️ MO The two letter representation of the first day of the week
$disableCharacterReplacement ☑️ false Toggles whether to disable all character replacement. Will replace curly quotes and other special characters with their standard equivalents if false. Can be a costly operation!
$eventCount ✖️ N/A Tracks the number of events in the current iCal feed
$filterDaysAfter ☑️ N/A When set the parser will ignore all events more than roughly this many days after now. To be on the safe side it is advised that you make the filter window +/- 1 day larger than necessary. For performance reasons this filter is applied before any date and time zone calculations are done. Hence, depending the time zone settings of the parser and the calendar the cut-off date is not "calibrated". You can then use $ical->eventsFromRange() to precisely shrink the window.
$filterDaysBefore ☑️ N/A When set the parser will ignore all events more than roughly this many days before now. See $filterDaysAfter above for more details.
$freeBusyCount ✖️ N/A Tracks the free/busy count in the current iCal feed
$replaceWindowsTimeZoneIds ☑️ false Toggles whether to replace (non-CLDR) Windows time zone IDs with their IANA equivalent e.g. "Mountain Standard Time" would be replaced with "America/Denver". As there are 130+ Windows time zone IDs that need to be searched and replaced this flag should only be turned on if you know that your calendar file contains such time zone IDs. Microsoft Exchange calendars are often seen using such IDs.
$skipRecurrence ☑️ false Toggles whether to skip the parsing of recurrence rules
$todoCount ✖️ N/A Tracks the number of todos in the current iCal feed
$useTimeZoneWithRRules ☑️ false Toggles whether to use time zone info when parsing recurrence rules

Methods

Method Parameter(s) Visibility Description
__construct $files = false, $options = array() public Creates the ICal object
initFile $file protected Initialises lines from a file
initLines $lines protected Initialises the parser using an array containing each line of iCal content
initString $string protected Initialises lines from a string
initUrl $url protected Initialises lines from a URL
addCalendarComponentWithKeyAndValue $component, $keyword, $value protected Add one key and value pair to the $this->cal array
calendarDescription - public Returns the calendar description
calendarName - public Returns the calendar name
calendarTimeZone $ignoreUtc public Returns the calendar time zone
cleanData $data protected Replaces curly quotes and other special characters with their standard equivalents
convertDayOrdinalToPositive $dayNumber, $weekday, $timestamp protected Converts a negative day ordinal to its equivalent positive form
eventsFromInterval $interval public Returns a sorted array of events following a given string, or false if no events exist in the range
eventsFromRange $rangeStart = false, $rangeEnd = false public Returns a sorted array of events in a given range, or an empty array if no events exist in the range
events - public Returns an array of Events
fileOrUrl $filename protected Reads an entire file or URL into an array
freeBusyEvents - public Returns an array of arrays with all free/busy events
hasEvents - public Returns a boolean value whether the current calendar has events or not
iCalDateToDateTime $icalDate, $forceTimeZone = false, $forceUtc = false public Returns a DateTime object from an iCal date time format
iCalDateToUnixTimestamp $icalDate, $forceTimeZone = false, $forceUtc = false public Returns a Unix timestamp from an iCal date time format
iCalDateWithTimeZone $event, $key, $format = DATE_TIME_FORMAT public Returns a date adapted to the calendar time zone depending on the event TZID
isExdateMatch $exdate, $anEvent, $recurringOffset protected Checks if an excluded date matches a given date by reconciling time zones
isFileOrUrl $filename protected Checks if a filename exists as a file or URL
isValidDate $value public Checks if a date string is a valid date
isValidTimeZoneId $timeZone protected Checks if a time zone is valid (IANA or CLDR)
isValidIanaTimeZoneId $timeZone protected Checks if a time zone is a valid IANA time zone
isValidCldrTimeZoneId $timeZone, doConversion = false protected Checks if a time zone is a valid CLDR time zone
keyValueFromString $text protected Gets the key value pair from an iCal string
mb_chr $code protected Provides a polyfill for PHP 7.2's mb_chr(), which is a multibyte safe version of chr()
mb_str_replace $search, $replace, $subject, $count = 0 protected Replaces all occurrences of a search string with a given replacement string
numberOfDays $days, $start, $end protected Gets the number of days between a start and end date
parseDuration $date, $duration, $format = 'U' protected Parses a duration and applies it to a date
parseExdates $event public Parses a list of excluded dates to be applied to an Event
processDateConversions - protected Processes date conversions using the time zone
processEventIcalDateTime $event, $index = 3 protected Extends the {DTSTART|DTEND|RECURRENCE-ID}_array array to include an iCal date time for each event
processEvents - protected Performs admin tasks on all events as read from the iCal file
processRecurrences - protected Processes recurrence rules
removeUnprintableChars $data protected Removes unprintable ASCII and UTF-8 characters
sortEventsWithOrder $events, $sortOrder = SORT_ASC public Sorts events based on a given sort order
trimToRecurrenceCount $rrules, $recurrenceEvents protected Ensures the recurrence count is enforced against generated recurrence events
unfold $lines protected Unfolds an iCal file in preparation for parsing

Constants

Name Description
DATE_TIME_FORMAT_PRETTY Default pretty date time format to use
DATE_TIME_FORMAT Default date time format to use
ICAL_DATE_TIME_TEMPLATE String template to generate an iCal date time
RECURRENCE_EVENT Used to isolate generated recurrence events
SECONDS_IN_A_WEEK The number of seconds in a week
TIME_FORMAT Default time format to use
TIME_ZONE_UTC UTC time zone string
UNIX_FORMAT Unix timestamp date format
UNIX_MIN_YEAR The year Unix time began

Event API (extends ICal API)

Methods

Method Parameter(s) Visibility Description
__construct $data = array() public Creates the Event object
prepareData $value protected Prepares the data for output
printData $html = HTML_TEMPLATE public Returns Event data excluding anything blank within an HTML template
snakeCase $input, $glue = '_', $separator = '-' protected Converts the given input to snake_case

Constants

Name Description
HTML_TEMPLATE String template to use when pretty printing content

Credits

  • Jonathan Goode (programming, bug fixing, enhancement, coding standard)
  • John Grogg (programming, addition of event recurrence handling)

Tools for Testing