forked from UsrSpace-Internal/website
179 lines
17 KiB
Markdown
179 lines
17 KiB
Markdown
|
# PHP ICS Parser
|
||
|
|
|
||
|
|
[](https://packagist.org/packages/johngrogg/ics-parser)
|
||
|
|
[](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) or [Unicode CLDR](http://cldr.unicode.org/translation/timezones) Time Zones
|
||
|
|
|
||
|
|
### 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 | Description | Configurable | Default Value |
|
||
|
|
|--------------------------------|---------------------------------------------------------------------|:------------------------:|-------------------------------------------------------------------------------------------|
|
||
|
|
| `$defaultSpan` | The value in years to use for indefinite, recurring events | :ballot_box_with_check: | `2` |
|
||
|
|
| `$defaultTimeZone` | Enables customisation of the default time zone | :ballot_box_with_check: | [System default](https://secure.php.net/manual/en/function.date-default-timezone-get.php) |
|
||
|
|
| `$defaultWeekStart` | The two letter representation of the first day of the week | :ballot_box_with_check: | `MO` |
|
||
|
|
| `$disableCharacterReplacement` | Toggles whether to disable all character replacement | :ballot_box_with_check: | `false` |
|
||
|
|
| `$skipRecurrence` | Toggles whether to skip the parsing of recurrence rules | :ballot_box_with_check: | `false` |
|
||
|
|
| `$useTimeZoneWithRRules` | Toggles whether to use time zone info when parsing recurrence rules | :ballot_box_with_check: | `false` |
|
||
|
|
| `$alarmCount` | Tracks the number of alarms in the current iCal feed | :heavy_multiplication_x: | N/A |
|
||
|
|
| `$cal` | The parsed calendar | :heavy_multiplication_x: | N/A |
|
||
|
|
| `$eventCount` | Tracks the number of events in the current iCal feed | :heavy_multiplication_x: | N/A |
|
||
|
|
| `$freeBusyCount` | Tracks the free/busy count in the current iCal feed | :heavy_multiplication_x: | N/A |
|
||
|
|
| `$todoCount` | Tracks the number of todos in the current iCal feed | :heavy_multiplication_x: | N/A |
|
||
|
|
|
||
|
|
#### 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)
|