| 1 |
# Zap Calendar iCalendar Library |
| 2 |
|
| 3 |
(https://github.com/zcontent/icalendar) |
| 4 |
|
| 5 |
@license type defined in source files: GNU General Public License version 2 or later; |
| 6 |
|
| 7 |
The Zap Calendar iCalendar Library is a PHP library for supporting the iCalendar (RFC 5545) standard. |
| 8 |
|
| 9 |
This PHP library is for reading and writing iCalendar formatted feeds and |
| 10 |
files. Features of the library include: |
| 11 |
|
| 12 |
- Read AND write support for iCalendar files |
| 13 |
- Object based creation and manipulation of iCalendar files |
| 14 |
- Supports expansion of RRULE to a list of repeating dates |
| 15 |
- Supports adding timezone info to iCalendar file |
| 16 |
|
| 17 |
All iCalendar data is stored in a PHP object tree. |
| 18 |
This allows any property to be added to the iCalendar feed without |
| 19 |
requiring specialized library function calls. |
| 20 |
With power comes responsibility. Missing or invalid properties can cause |
| 21 |
the resulting iCalendar file to be invalid. Visit [](http://icalendar.orgiCalendar.org](http://icalendar.org](http://icalendar.org) to view valid |
| 22 |
properties and test your feed using the site's [](http://icalendar.org/validator.htmliCalendar validator tool](http://icalendar.org/validator.html](http://icalendar.org/validator.html). |
| 23 |
|
| 24 |
See the examples folder for programs that read and write iCalendar |
| 25 |
files. At its simpliest, you need to include the library at the top of your program: |
| 26 |
|
| 27 |
```php |
| 28 |
require_once($path_to_library . "/zapcallib.php"); |
| 29 |
``` |
| 30 |
|
| 31 |
Create an ical object using the ZCiCal object: |
| 32 |
|
| 33 |
```php |
| 34 |
$icalobj = new ZCiCal(); |
| 35 |
``` |
| 36 |
|
| 37 |
Add an event object: |
| 38 |
|
| 39 |
```php |
| 40 |
$eventobj = new ZCiCalNode("VEVENT", $icalobj->curnode); |
| 41 |
``` |
| 42 |
|
| 43 |
Add a start and end date to the event: |
| 44 |
|
| 45 |
```php |
| 46 |
// add start date |
| 47 |
$eventobj->addNode(new ZCiCalDataNode("DTSTART:" . ZCiCal::fromSqlDateTime("2020-01-01 12:00:00"))); |
| 48 |
|
| 49 |
// add end date |
| 50 |
$eventobj->addNode(new ZCiCalDataNode("DTEND:" . ZCiCal::fromSqlDateTime("2020-01-01 13:00:00"))); |
| 51 |
``` |
| 52 |
|
| 53 |
Write the object in iCalendar format using the export() function call: |
| 54 |
|
| 55 |
```php |
| 56 |
echo $icalobj->export(); |
| 57 |
``` |
| 58 |
|
| 59 |
This example will not validate since it is missing some required elements. |
| 60 |
Look at the simpleevent.php example for the minimum # of elements |
| 61 |
needed for a validated iCalendar file. |
| 62 |
|
| 63 |
To read an existing iCalendar file/feed, create the ZCiCal object with a string representing the contents of the iCalendar file: |
| 64 |
|
| 65 |
```php |
| 66 |
$icalobj = new ZCiCal($icalstring); |
| 67 |
``` |
| 68 |
|
| 69 |
## Known Limitations |
| 70 |
|
| 71 |
- Since the library utilizes objects to read and write iCalendar data, the |
| 72 |
size of the iCalendar data is limited to the amount of available memory on the machine. |
| 73 |
The ZCiCal() object supports reading a range of events to minimize memory |
| 74 |
space. |
| 75 |
- The library ignores timezone info when importing files, instead utilizing PHP's timezone |
| 76 |
library for calculations (timezones are supported when exporting files). |
| 77 |
Imported timezones need to be aliased to a [](http://php.net/manual/en/timezones.phpPHP supported timezone](http://php.net/manual/en/timezones.php](http://php.net/manual/en/timezones.php). |
| 78 |
- At this time, the library does not support the "BYSETPOS" option in RRULE items. |
| 79 |
- At this time, the maximum date supported is 2036 to avoid date math issues |
| 80 |
with 32 bit systems. |
| 81 |
- Repeating events are limited to a maximum of 5,000 dates to avoid memory or infinite loop issues |
| 82 |
|
| 83 |
|
