README

PHP ICS 解析器

安装

需求

• PHP 5 (≥ 5.6.40)
• 有效的 ICS (文件 .ics, .ical, .ifb)
• IANA, Unicode CLDR 或 Windows 时区

设置

• 安装 Composer
  • 将以下依赖项添加到 composer.json
    • ⚠️ 注意：Composer 中的所有者是 johngrogg 而不是 u01jmg3
  • 要访问最新稳定分支（v3），请使用以下命令

    • 要访问新功能，可以要求 dev-master

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

运行测试

composer test

如何使用

如何实例化解析器

• 以示例脚本文档为指南，参考此代码

解析器将返回什么？

• 从 iCal 文件解析每个键/值对，为日历及其包含的每个事件创建关联数组。

• 还将注入 dtstart_tz 和 dtend_tz 下的内容，以便在应用时区数据的情况下访问开始和结束日期。

• 尽可能使用 DateTime 对象，并返回。

  • ℹ️ 注意：解析器仅限于 相对日期格式，这可能会妨碍处理复杂的重复规则部分（例如，将 BYDAY 与 BYSETPOS 结合）

  // Dump the whole calendar
  var_dump($ical->cal);
  
  // Dump every event
  var_dump($ical->events());

• 还包括特殊的 {property}_array 数组，它们进一步解析键/值对的内容。

  // 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)

您是否使用 Outlook？

Outlook 有一个怪癖，它要求在您的请求头中设置用户代理字符串。

我们已为您注入默认用户代理字符串，如果尚未指定。

如果您希望提供自己的用户代理字符串，可以在创建 ICal 对象时使用 httpUserAgent 参数。

$ical = new ICal($url, array('httpUserAgent' => 'A Different User Agent'));

解析 iCal 资源时

解析 iCal/iCalendar/ICS 资源可能会带来一些挑战。一个挑战是规范是一个移动的目标；原始 RFC 在十年内只更新了四次。另一个挑战是供应商在解释规范时既自由（即：富有创意）又积极实现专有扩展。

然而，最直接阻碍高效解析的是事件的重复规则。这个库将原始日历解析成易于操作的内存模型。这需要将每个重复事件展开或分解。因此，每天发生一次的单个事件将在解析日历时生成新的事件实例（$defaultSpan 限制了这一点）。要了解如何做到这一点，请查看调用图。

因此，整个日历必须逐行解析，首先加载到内存中。正如你所想象的，大型日历在展开时（即，所有重复规则都被评估时）往往会变得非常大。当旧日历每年变得更加庞大时，这种情况会加剧。

如果你只需要查看原始日历的一个窗口，这种限制尤其痛苦。如果你稍后要调用eventsFromInterval() 或 eventsFromRange()，将整个完全展开的日历解析到内存中似乎是一种浪费。

在2018年底，#190 增加了在解析过程中非常早期就丢弃给定范围之外所有事件的功能，这以牺牲一些精度为代价（在那个点不会计算时区计算）。这大大减少了解析日历的总时间。同样，这也适用于内存消耗。前提是你事先知道你不在乎给定范围之外的事件。

比如说，你只对昨天的、今天的和明天的活动感兴趣。为了补偿在解析器决定保留或丢弃事件时，复杂的时区转换和计算尚未执行的事实，你可以将其设置为过滤 +-2d 而不是 +-1d。一旦完成，你就可以调用 eventsFromRange()，加上 +-1d，以精确地获取你感兴趣的窗口中的活动。这就是变量 $filterDaysBefore 和 $filterDaysAfter 的作用。

在2019年第一季度，#213 通过在解析后立即丢弃 非重复 事件（如果它们不在模糊窗口内）来进一步提高了性能。这大大减少了大型日历的最大内存消耗。PHP默认情况下不会分配超过128MB堆栈，否则会因Fatal error: Allowed memory size of 134217728 bytes exhausted而崩溃。不言而喻，在丢弃不匹配事件之前，必须先评估重复事件。

API

ICal API

变量

方法

常量

Event API（扩展了ICal API）

方法

常量

致谢

• Jonathan Goode（编程、错误修复、代码库增强、编码标准采用）
• s0600204（对RRULE支持的重大增强，许多错误修复和其他贡献）

测试工具

• iCal验证器
• 重复规则测试器
• Unix时间戳转换器