README

(https://github.com/zcontent/icalendar)

Zap Calendar iCalendar 库是一个支持 iCalendar（RFC 5545）标准的 PHP 库。

此 PHP 库用于读取和写入 iCalendar 格式的源和文件。库的特点包括：

• 支持读取和写入 iCalendar 文件
• 基于对象的 iCalendar 文件创建和操作
• 支持将 RRULE 扩展到重复日期列表
• 支持将时区信息添加到 iCalendar 文件

所有 iCalendar 数据都存储在 PHP 对象树中。这允许在不要求调用专用库函数的情况下向 iCalendar 源添加任何属性。权力伴随着责任。缺失或无效的属性可能导致生成的 iCalendar 文件无效。请访问 iCalendar.org 以查看有效属性并使用网站的 iCalendar 验证工具 测试您的源。

库 API 文档可在 http://icalendar.org/zapcallibdocs 找到

请参阅示例文件夹，以获取读取和写入 iCalendar 文件的程序。在最简单的情况下，您需要在程序顶部包含库

require_once($path_to_library . "/zapcallib.php");

使用 ZCiCal 对象创建 iCalendar 对象

$icalobj = new ZCiCal();

添加事件对象

$eventobj = new ZCiCalNode("VEVENT", $icalobj->curnode);

添加事件开始和结束日期

// add start date
$eventobj->addNode(new ZCiCalDataNode("DTSTART:" . ZCiCal::fromSqlDateTime("2020-01-01 12:00:00")));

// add end date
$eventobj->addNode(new ZCiCalDataNode("DTEND:" . ZCiCal::fromSqlDateTime("2020-01-01 13:00:00")));

使用 export() 函数调用以 iCalendar 格式写入对象

echo $icalobj->export();

此示例将不会验证，因为它缺少一些必需元素。请查看 simpleevent.php 示例，了解验证 iCalendar 文件所需的最小元素数量。

要创建多事件 iCalendar 文件，只需创建多个事件对象。例如

$icalobj = new ZCiCal();
$eventobj1 = new ZCiCalNode("VEVENT", $icalobj->curnode);
$eventobj1->addNode(new ZCiCalDataNode("SUMMARY:Event 1"));
...
$eventobj2 = new ZCiCalNode("VEVENT", $icalobj->curnode);
$eventobj2->addNode(new ZCiCalDataNode("SUMMARY:Event 2"));
...

要读取现有的 iCalendar 文件/源，使用表示 iCalendar 文件内容的字符串创建 ZCiCal 对象

$icalobj = new ZCiCal($icalstring);

大 iCalendar 文件可以分块读取，以减少在内存中保留 iCalendar 源所需的内存量。此示例每次读取 500 个事件

$icalobj = null;
$eventcount = 0;
$maxevents = 500;
do
{
	$icalobj = newZCiCal($icalstring, $maxevents, $eventcount);
	...
	$eventcount +=$maxevents;
}
while($icalobj->countEvents() >= $eventcount);

您可以以这种方式从导入（或创建）的 iCalendar 对象中读取事件

foreach($icalobj->tree->child as $node)
{
	if($node->getName() == "VEVENT")
	{
		foreach($node->data as $key => $value)
		{
			if($key == "SUMMARY")
			{
				echo "event title: " . $value->getValues() . "\n";
			}
		}
	}
}

已知限制

• 由于库使用对象来读取和写入 iCalendar 数据，iCalendar 数据的大小受机器上可用内存的限制。ZCiCal() 对象支持读取一系列事件以最小化内存空间。
• 库在导入文件时忽略时区信息，而是利用 PHP 的时区库进行计算（导出文件时支持时区）。导入的时区需要别名到 PHP 支持的时区。
• 目前，库不支持 RRULE 项中的 "BYSETPOS" 选项。
• 目前，支持的最大日期为 2036 年，以避免与 32 位系统的日期数学问题。
• 重复事件的数量限制为 5,000 个日期，以避免内存或无限循环问题