jasonheffner / ics-parser

Parser for iCalendar events · written in PHP 5 (≥ 5.3.0)

PHP ICS Parser

---

Installation

Requirements

• PHP 5 (≥ 5.3.0)
• Valid ICS (.ics, .ical, .ifb) file

Setup

• Install Composer

  • Add the following requirement to composer.json
    • ⚠️ Note the owner is johngrogg and not u01jmg3
  • If you want to try out newer features then require dev-master

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

How to instantiate the Parser

• Using the example script as a guide, refer to this code

---

API

ICal API

Constants

Name	Description
DATE_TIME_FORMAT	Default datetime format to use
RECURRENCE_EVENT	Used to isolate generated recurrence events
SECONDS_IN_A_WEEK	Integer of the number of seconds in a week
TIME_FORMAT	Default time format to use
UNIX_MIN_YEAR	Minimum UNIX year to use

Variables

Name	Description	Configurable	Default Value
$cal	The parsed calendar	❌	N/A
$eventCount	Track the number of events in the current iCal feed	❌	N/A
$freeBusyCount	Track the free/busy count in the current iCal feed	❌	N/A
$todoCount	Track the number of todos in the current iCal feed	❌	N/A
$defaultSpan	The value in years to use for indefinite, recurring events	✅	2
$defaultTimeZone	Customise the default time zone used by the parser	✅	System default
$defaultWeekStart	The two letter representation of the first day of the week	✅	MO
$skipRecurrence	Toggle whether to skip the parsing recurrence rules	✅	false
$useTimeZoneWithRRules	Toggle whether to use time zone info when parsing recurrence rules	✅	false

Functions

Function	Parameter(s)	Visibility	Description
__construct	$files = false, $options = array()	public	Creates the ICal object
initLines	$lines	protected	Initialises lines from a file
initString	$string	protected	Initialises lines from a string
initUrl	$url	protected	Initialises lines from a URL
cleanData	$data	protected	Replace curly quotes and other special characters with their standard equivalents
convertDayOrdinalToPositive	$dayNumber, $weekday, $timestamp	protected	Convert a negative day ordinal to its equivalent positive form
isValidTimeZoneId	$timeZone	protected	Check if a time zone is valid
mb_str_replace	$search, $replace, $subject, $count = 0	protected	Replace all occurrences of the search string with the replacement string. Multibyte safe.
numberOfDays	$days, $start, $end	protected	Get the number of days between a start and end date
parseDuration	$date, $duration	protected	Parse a duration and apply it to a date
processDateConversions	-	protected	Add fields DTSTART_tz and DTEND_tz to each Event
processEvents	-	protected	Performs some admin tasks on all events as taken straight from the ics file.
processRecurrences	-	protected	Processes recurrence rules
removeUnprintableChars	$data	protected	Remove unprintable ASCII and UTF-8 characters
unfold	$lines	protected	Unfold an iCal file in preparation for parsing
calendarDescription	-	public	Returns the calendar description
calendarName	-	public	Returns the calendar name
calendarTimeZone	-	public	Returns the calendar time zone
events	-	public	Returns an array of Events. Every event is a class with the event details being properties within it.
eventsFromInterval	$interval	public	Returns a sorted array of the 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 the events in a given range, or an empty array if no events exist in the range.
freeBusyEvents	-	public	Returns an array of arrays with all free/busy events. Every event is an associative array and each property is an element it.
hasEvents	-	public	Returns a boolean value whether the current calendar has events or not
iCalDateToUnixTimestamp	$icalDate	public	Return Unix timestamp from iCal date time format
iCalDateWithTimeZone	$event, $key, $forceTimeZone	public	Return a date adapted to the calendar time zone depending on the event TZID
isValidDate	$value	public	Check if a date string is a valid date
parseExdates	$event	public	Parse a list of excluded dates to be applied to an Event
sortEventsWithOrder	$events, $sortOrder = SORT_ASC	public	Sort events based on a given sort order

---

Event API

Functions

Function	Parameter(s)	Description
__construct	$data = array()	Creates the Event object
prepareDate	$value	Prepares the data for output
printData	$html = '<p>%s: %s</p>'	Return Event data excluding anything blank within an HTML template

---

Credits

• Jonathan Goode (programming, bug fixing, enhancement, coding standard)
• John Grogg (programming, addition of event recurrence handling)
• Frank Gregor (programming, feedback, testing)
• Martin Thoma (programming, bug fixing, project management, initial concept)

---

Tools for Testing

• https://jakubroztocil.github.io/rrule/
• http://www.unixtimestamp.com/