README

主分支：

Calendar 是一个PHP库，用于创建由自定义事件源组成的自定义日历。创建的日历可以轻松转换为各种输出格式（例如 Json、iCalendar (ics)、FullCalendar 等）。

// (1) service container (used to retrieve calendars, sources, events etc.)
// see full example below for use of own service container
$services = include 'config/services.config.php';
$serviceContainer = new Zend\ServiceManager\ServiceManager($services);

// (2) calendar builder
$config = include 'config/config.php'; // optional config array (see configuration section below)
$calendarBuilder = $serviceContainer->build(CalendarBuilder::class, $config);
$calendar = $calendarBuilder->build('SomeCalendarName');
$calendar->addSource(SomeCalendarSource::class);
$events = $calendar->getEvents(); // retrieve traversable collection of calendar events

// convert calendar into json
$json = Converter::convert($calendar, 'json'); // second parameter can as well be a converter classname

// convert calendar into "iCalendar" format (RFC 2445, VCALENDAR)
$ics = Converter::convert($calendar, 'ical'); // second parameter can as well be a converter classname

// convert calendar into "FullCalendar" JSON format (see https://github.com/fullcalendar/fullcalendar)
$fcJson = Converter::convert($calendar, 'FullCalendar');

完整示例

配置

可选配置允许您声明自己的转换器以及事件颜色和颜色策略。如果未传递任何配置给 CalendarBuilderFactory，则内部创建一个空配置。

以下是一个基本示例配置文件：

<?php

namespace Elchristo\Calendar;

return [
    'elchristo' => [

        'calendar' => [

            // your own converter strategies (optional)
            'converters' => [
                'MyJsonConverterAlias' => [
                    MyJsonConverter\Event\MyEventType::class => MyJsonConverter\ClassName::class
                ]
            ],

            // event color configuration
            'colors' => [
                'codes' => [
                    // some predefined color codes to be used by e.g. a color strategy

                ],
                'strategies' => [
                    'MyColorStrategy' => My\ColorStrategy\ClassName::class
                ]
            ]

        ]
    ]
];

构建事件源

要构建事件源，您只需创建一个实现 SourceInterface 的类，或者更简单的是，通过默认属性和行为扩展 AbstractSource 类。之后，您只需实现两个方法 fetchResults 和 buildEvents。

示例源类

<?php

use Elchristo\Calendar\Model\Source\AbstractSource;

class MySource extends AbstractSource
{
    protected function fetchResults()
    {
        /*
         * Retrieve your events data from wherever you want (database, file, ...)
         * This should result in an associative array like the example below
         * Hint : array keys matching event property names makes it easy to transform results into events
         */
        $events = [
            0 => [
                'id' => 1,
                'start' => new \DateTime(),
                'end' => new \DateTime,
                'title' => 'event title 1',
                'description' => 'a brief description',
                'alldayEvent' => false
            ],
            . . .
        ];

        return $events;‚
    }

    protected function buildEvents($results)
    {
        // this method is called after the "fetchResults" methods and recieves its results ...

        $eventsBuilder = $this->getEventBuilder();
        $eventsCollection = $this->getEventsCollection();

        foreach ($results as $result) {
            $event = $eventsBuilder->build(MyEvent::class, $result, $this->getOptions());
            $eventsCollection->add($event);
        }

        return $eventsCollection;
    }
}

检索日历构建器

// solution 1 : using pre-configured internal ZF service manager component
$services = include 'config/services.config.php';
$sm = new Zend\ServiceManager\ServiceManager($services);
$calendarBuilder = $sm->get(CalendarBuilder::class);

// solution 2 : using own ZF service manager
// Important : you need to integrate the content of included services.config.php file into your app configuration
$sm = $this->getServiceLocator();
$config = include 'config/config.php'; // calendar config (converters, color strategies, ...)
$calendarBuilder = $sm->build(CalendarBuilder::class, $config);

构建日历并添加事件源

然后使用它来构建您的日历实例并添加任何定义的日历源。

$calendar = $calendarBuilder->build('MyFirstCalendar');
// if no class with passed calendar name can be found an empty default calendar named "MyFirstCalendar" is built

$calendar
    ->addSource(SourceA::class)
    ->addSource(SourceB::class);

// sourceA and sourceB must be valid calendar sources (implement "SourceInterface")

检索日历事件

当您在日历实例上调用 getEvents 方法时，组件将检索每个源的数据结果并构建标准化的日历事件（由源类实现）。只需遍历结果集合并对其进行处理。

$events = $calendar->getEvents();
foreach ($events as $event) :
    echo $event->getId();
    echo $event->getTitle();
    echo $event->getDescription();
    echo $event->getStart()->format('d/m/Y H:i');
    echo $event->getEnd()->format('d/m/Y H:i');
endforeach;

选项

prefix_identifier

字符串

此选项用于前缀事件 ID（如果有不同来源可能检索具有相同标识符的事件，则是有意义的）

color_strategy

字符串 或 数组

如果您的源包含实现 ColoredEventInterface 的日历事件，您可能对使用颜色策略感兴趣。颜色策略允许您根据条件对事件进行着色。例如，如果您想根据事件是否公开来应用颜色，则可以为此实现颜色策略。

构建日历源时（在日历内）可以使用以下选项。注意：您必须在容器配置中声明颜色策略作为服务。

'color_strategy' => ColorByEventStatus::class

'color_strategy' => [
    'name' => ColorByEventStatus::class,
    'attributes' => [
        ...
    ]
]

示例颜色策略类实现

use Elchristo\Calendar\Service\Color\AbstractColorStrategy;

class ColorByEventStatus extends AbstractColorStrategy
{
    public function getColorCodeByEvent()
    {
        return ($this->getEvent()->isPublic())
            ? '#00ff00'
            : '#ff0000';
    }
}

转换器

一旦您使用单个事件源构建了您的日历，您就可以轻松地将检索到的日历事件转换为各种输出格式。转换器允许您将事件转换为新的结构。这些被称为 可转换事件。

日历组件自带内置转换器（json，ical），但您也可以使用 Elchristo\Calendar\Converter\AbstractConverter 创建自己的转换器，该转换器实现了 Elchristo\Calendar\Converter\ConverterInterface。此外，您还需要创建至少一个默认的 可转换事件（实现 Elchristo\Calendar\Converter\ConvertibleEventInterface），以指定其结构。如果您的日历包含具有不同格式的事件，则可以为每个格式创建一个 可转换事件。

为了避免自动加载问题，我们建议遵守以下目录结构和文件命名约定：

MyConverter/MyConverter.php
MyConverter/Event/DefaultMyConverterEvent.php

转换器和其 可转换事件 必须在配置文件中的 converters 键下声明（请参阅配置示例）。

测试

// to run tests with codeceptions
php ./vendor/bin/codecept run unit

elchristo / calendar

维护者

详细信息