README

注意： 在Contao 4中已过时 - 仅对Contao 4扩展，您应直接使用symfony内核的事件分发器。有关与两个Contao版本保持兼容性的说明，请参阅以下内容。

Contao开源CMS的事件分发器

为什么Contao开源CMS需要一个事件分发器，钩子不是足够吗？首先，您需要理解，钩子和事件之间没有真正的区别。它们都是从系统内部发出的通知。

但事件比钩子更灵活。它们可以被传递、消费、停止或沿层次结构冒泡。

事件分发器在Contao中存在的主要原因包括

1. 事件是软件设计中的标准范式。
2. 钩子是改变软件行为的范式，但它不是为通知而设计的。
3. 钩子只是事件的一种特殊形式。
4. 此扩展基于广泛使用的symfony事件分发器。
5. 事件分发器可以处理各种回调形式，如闭包或静态方法。

监听事件

事件分发器提供两种方式来监听事件。

首先也是最常用的方法是事件监听器。它被设计为监听单个事件。

第二种方法是事件订阅者，它被设计为监听多个事件。

按配置定义事件监听器

从版本1.3开始，有两种方式可以按配置定义监听器。

/config/event_listeners.php

我们建议使用此方法！

文件/config/event_listeners.php必须返回一个数组，其中键是事件名称，值是监听器。

<?php
return array(
    // With a closure
    'event-name' => array(
        function($event) {
            // event code
        }
    ),
    
    // With a static callable
    'event-name' => array(
        array('MyEventListener', 'myCallable')
    ),
    
    // With an object callable
    'event-name' => array(
        array(new MyEventListener(), 'myCallable')
    ),
    
    // With a service object
    'event-name' => array(
        array($GLOBALS['container']['my_event_listener'], 'myCallable')
    ),
    
    // You can wrap the listener into an array with a priority
    'event-name' => array(
        array($listener, $priority)
    ),
);

/config/config.php

在您的/config/config.php中使用$GLOBALS['TL_EVENTS']来注册您的事件处理器。

使用闭包

$GLOBALS['TL_EVENTS']['event-name'][] = function($event) {
    // event code
};

使用静态调用

$GLOBALS['TL_EVENTS']['event-name'][] = array('MyEventListener', 'myCallable');

使用对象调用

$GLOBALS['TL_EVENTS']['event-name'][] = array(new MyEventListener(), 'myCallable');

按优先级处理

要定义优先级，可以使用包含监听器和优先级元素的数组。

$GLOBALS['TL_EVENTS']['event-name'][] = array($listener, $priority);

按代码定义事件监听器

$container['event-dispatcher']->addListener('event-name', $listener);

按配置定义事件订阅者

从版本1.3开始，有两种方式可以按配置定义监听器。

/config/event_subscribers.php

我们建议使用此方法！

文件/config/event_subscribers.php必须返回一个订阅者数组。

<?php
return array(
    // With a factory
    function($eventDispatcher) {
        return new MyEventSubscriber();
    },
    
    // With an object class name
    'MyEventSubscriber',
    
    // With an object instance
    new MyEventSubscriber(),
    
    // With a service object
    $GLOBALS['container']['my_event_subscriber'],
);

/config/config.php

在您的/config/config.php中使用$GLOBALS['TL_EVENT_SUBSCRIBERS']来注册您的订阅者。

使用工厂

$GLOBALS['TL_EVENT_SUBSCRIBERS'][] = function($eventDispatcher) {
    return new MyEventSubscriber();
};

使用对象类名

$GLOBALS['TL_EVENT_SUBSCRIBERS'][] = 'MyEventSubscriber';

使用对象实例

$GLOBALS['TL_EVENT_SUBSCRIBERS'][] = new MyEventSubscriber();

按代码定义事件订阅者

$container['event-dispatcher']->addSubscriber(new MyEventSubscriber());

与Contao 3和4的兼容性

鼓励您在Contao 4中使用服务配置文件（yaml、xml等）直接在symfony事件分发器中注册事件。

然而，为了保持兼容性，您仍然需要提供event_listeners.php和event_subscribers.php文件，否则事件将不会在Contao 3中注册。

为了仅在Contao 3中注册事件，我们建议在版本比较等于4时返回空数组。

 <?php
 
+ // Contao 4 registers events via symfony configuration.
+ if (version_compare(VERSION, '4.0', '>=')) {
+     return [];
+ }
 
 return [
     'some.event' => ['Some\EventListener', 'someMethod']
 ];