README

该 iCalendar 库提供了创建、编辑和导入 RFC 5545 - 互联网日历和调度 (iCalendar) 的能力，包括在 RFC 7986 - iCalendar 的新属性中定义的属性。

创建 iCalendars

iCalendar 库允许以面向对象的方式创建 iCalendars。

要创建一个 iCalendar，创建一个新的 Vcalendar 对象，然后向其中添加属性和组件；以类似的方式向子组件添加属性和其他组件；支持相同类型的多个组件，以及组件中具有相同名称的多个属性。

最后，调用 Vcalendar 的 render() 方法。

所有 iCalendar 组件都是不可变的。

UIDs

VEVENT、VFREEBUSY、VJOURNAL 和 VTODO 组件需要 UID 属性；自 RFC 7985 以来，它也可以在 VCALENDAR 中设置。RFC 7985 更新了构造值建议；它废弃了使用 IP 地址以及主机和域名名的做法，尤其是出于隐私和安全问题的考虑，并建议使用在 4.4 和 4.5 节中定义的通用唯一标识符 (UUID) 值 RFC4122。

该库提供了一个生成 V4 UUIDs 的辅助方法。

$vCalendar = (new Vcalendar())
    ->addProperty(Vcalendar::PROPERTY_UID, Vcalendar::uuidv4())
    ->addComponent((new Vevent())
        ->addProperty(Vevent::PROPERTY_UID, Vevent::uuidv4())
    )
;

非标准组件

IANA 和 X- 组件可以添加到 iCalender 对象 (Vcalendar) 中。

非标准组件必须在使用前扩展 Component 并定义 NAME 常量；它们必须在 Vcalendar 中注册。

use BeastBytes\ICalendar\Component;

class NonStandardComponent extends Component
{
    public const NAME = 'NON-STANDARD-COMPONENT';

    protected const CARDINALITY = [
        // declare cardinality of the component's properties here
    ];
}
---
Vcalendar::registerNonStandardComponent(NonStandardComponent::NAME);

$nonStandardComponent = new NonStandardComponent();

$vCalendar = (new Vcalendar())->addComponent($nonStandardComponent);
// $vCalendar->hasComponent(NonStandardComponent::NAME) === true;

非标准属性

IANA 和 X- 属性可以添加到 iCalender 组件中。

非标准属性在使用前必须向组件注册；默认基数为一，可能存在多个。

public const NON_STANDARD_PROPERTY = 'NON-STANDARD-PROPERTY';

Vevent::registerNonStandardProperty(self::NON_STANDARD_PROPERTY, Vevent::CARDINALITY_ONE_MAY);

$vEvent = (new Vevent())->addProperty(self::NON_STANDARD_PROPERTY, $value);
// $vEvent->hasProperty(self::NON_STANDARD_PROPERTY) === true;

示例

以下示例创建了一个带有闹钟的待办事项（它是 RFC5545 第 146 页上的示例，已修改为使用 UUID V4 作为 UID）。

$iCalendar = (new Vcalendar())
    ->addProperty(Vcalendar::PROPERTY_PRODUCT_IDENTIFIER, '-//ABC Corporation//NONSGML My Product//EN')
    ->addComponent((new Vtodo())
        ->addProperty(Vtodo::PROPERTY_DATETIME_STAMP, '19980130T134500Z')
        ->addProperty(Vtodo::PROPERTY_SEQUENCE, 2)
        ->addProperty(Vtodo::PROPERTY_UID, Vtodo::uuidv4())
        ->addProperty(Vtodo::PROPERTY_ORGANIZER, 'mailto:unclesam@example.com')
        ->addProperty(
            Vtodo::PROPERTY_ATTENDEE,
            'mailto:jqpublic@example.com',
            [
                Vtodo::PARAMETER_PARTICIPATION_STATUS => Vtodo::STATUS_ACCEPTED
            ]
        )
        ->addProperty(Vtodo::PROPERTY_DATETIME_DUE, '19980415T000000')
        ->addProperty(Vtodo::PROPERTY_STATUS, Vtodo::STATUS_NEEDS_ACTION)
        ->addProperty(Vtodo::PROPERTY_SUMMARY, 'Submit Income Taxes')
        ->addComponent((new Valarm())
            ->addProperty(Valarm::PROPERTY_ACTION, Valarm::ACTION_AUDIO)
            ->addProperty(Valarm::PROPERTY_TRIGGER, '19980403T120000Z')
            ->addProperty(
                Valarm::PROPERTY_ATTACH,
                'http://example.com/pub/audio-files/ssbanner.aud',
                [
                    Valarm::PARAMETER_FORMAT_TYPE => 'audio/basic'
                ]
            )
            ->addProperty(Valarm::PROPERTY_REPEAT, 4)
            ->addProperty(Valarm::PROPERTY_DURATION, 'PT1H')
        )
    )
    ->render()
;

查看测试以获取更多示例。

编辑 iCalendar

iCalendar 组件可以编辑，例如在更新 Vevent 时。

该库提供了用于编辑组件的方法

hasComponent($name) - 检查组件是否包含一个或多个类型为 $name 的组件
getComponents() - 返回所有子组件
getComponent($name) - 返回所有类型为 $name 的子组件
getComponent($name, $n) - 返回类型为 $name 的第 $n 个子组件
setComponent($component, $n) - 设置（覆盖）第 $n 个类型为 $component 的组件
removeComponent($name) - 删除所有类型为 $name 的子组件
removeComponent($name, $n) - 删除类型为 $name 的第 $n 个子组件
hasProperty($name) - 检查组件是否包含一个或多个类型为 $name 的属性
getProperties() - 返回所有组件属性
getProperty($name) - 返回所有类型为 $name 的组件属性
getProperty($name, $n) - 返回类型为 $name 的第 $n 个组件属性
setProperty($name, $n, $value, $parameters) - 设置（覆盖）类型为 $name 的第 $n 个属性的新 $value 和 $parameters
removeProperty($name) - 删除所有类型为 $name 的组件属性
removeProperty($name, $n) - 删除类型为 $name 的组件属性的 $nth 个出现

导入 iCalendar

使用 Vcalendar::import() 方法导入 iCalendar 字符串

$icalendar = Vcalendar::import($string);

安装

安装库的首选方法是使用 composer。

可以运行

php composer.phar require --prefer-dist beastbytes/icalendar

或将以下内容添加到 composer.json 文件的 'require' 部分：

"beastbytes/icalendar": "*"

测试

单元测试

该包使用 PHPUnit 进行测试。要运行测试

./vendor/bin/phpunit

静态分析

使用 Psalm 进行代码的静态分析。要运行静态分析

./vendor/bin/psalm

许可证

iCalendar 库是免费软件。它根据 BSD 许可证的条款发布。有关许可证信息，请参阅 LICENSE 文件。

beastbytes / icalendar

维护者

详细信息