# PHP ICS Parser

[![Latest Stable Release](https://poser.pugx.org/johngrogg/ics-parser/v/stable.png "Latest Stable Release")](https://packagist.org/packages/johngrogg/ics-parser)
[![Total Downloads](https://poser.pugx.org/johngrogg/ics-parser/downloads.png "Total Downloads")](https://packagist.org/packages/johngrogg/ics-parser)

---

## Installation

### Requirements
 - PHP 5 (≥ 5.3.0)
 - [Valid ICS](https://icalendar.org/validator.html) (`.ics`, `.ical`, `.ifb`) file
 - [IANA](https://www.iana.org/time-zones), [Unicode CLDR](http://cldr.unicode.org/translation/timezones) or [Windows](https://support.microsoft.com/en-ca/help/973627/microsoft-time-zone-index-values) Time Zones
   - Windows will need the `$replaceWindowsTimeZoneIds = true` configuration

### Setup

 - Install [Composer](https://getcomposer.org/)
   - Add the following dependency to `composer.json`
     - :warning: **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`](https://getcomposer.org/doc/articles/aliases.md#branch-alias)

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

## How to use

### How to instantiate the Parser

 - Using the example script as a guide, [refer to this code](https://github.com/u01jmg3/ics-parser/blob/master/examples/index.php#L1-L22)

#### 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`](https://secure.php.net/manual/en/class.datetime.php) objects are used and returned.

   ```php
   // 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.

   ```php
   // 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`                  | :heavy_multiplication_x: | N/A                                                                                               | Tracks the number of alarms in the current iCal feed                                                                                                                                                                                                                                                                                                                                                              |
| `$cal`                         | :heavy_multiplication_x: | N/A                                                                                               | The parsed calendar                                                                                                                                                                                                                                                                                                                                                                                               |
| `$defaultSpan`                 | :ballot_box_with_check:  | `2`                                                                                               | The value in years to use for indefinite, recurring events                                                                                                                                                                                                                                                                                                                                                        |
| `$defaultTimeZone`             | :ballot_box_with_check:  | [System default](https://secure.php.net/manual/en/function.date-default-timezone-get.php)         | Enables customisation of the default time zone                                                                                                                                                                                                                                                                                                                                                                    |
| `$defaultWeekStart`            | :ballot_box_with_check:  | `MO`                                                                                              | The two letter representation of the first day of the week                                                                                                                                                                                                                                                                                                                                                        |
| `$disableCharacterReplacement` | :ballot_box_with_check:  | `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`                  | :heavy_multiplication_x: | N/A                                                                                               | Tracks the number of events in the current iCal feed                                                                                                                                                                                                                                                                                                                                                              |
| `$freeBusyCount`               | :heavy_multiplication_x: | N/A                                                                                               | Tracks the free/busy count in the current iCal feed                                                                                                                                                                                                                                                                                                                                                               |
| `$replaceWindowsTimeZoneIds`   | :ballot_box_with_check:  | `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`              | :ballot_box_with_check:  | `false`                                                                                           | Toggles whether to skip the parsing of recurrence rules                                                                                                                                                                                                                                                                                                                                                           |
| `$todoCount`                   | :heavy_multiplication_x: | N/A                                                                                               | Tracks the number of todos in the current iCal feed                                                                                                                                                                                                                                                                                                                                                               |
| `$useTimeZoneWithRRules`       | :ballot_box_with_check:  | `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](https://github.com/u01jmg3) (programming, bug fixing, enhancement, coding standard)
 - [John Grogg](john.grogg@gmail.com) (programming, addition of event recurrence handling)

---

## Tools for Testing

 - [iCal Validator](https://icalendar.org/validator.html)
 - [Recurrence Rule Tester](https://jakubroztocil.github.io/rrule/)
 - [Unix Timestamp Converter](https://www.unixtimestamp.com)
