README

安装

需求

• 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 时间戳转换器