[feature/event-dispatcher] Introduce a port of Symfony2 EventDispatcher

PHPBB3-9550

phpBB/includes/event/dispatcher.php

@@ -0,0 +1,185 @@
+<?php
+/**
+*
+* @package phpBB3
+* @copyright (c) 2011 phpBB Group
+* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
+*
+*/
+
+/**
+* @ignore
+*/
+if (!defined('IN_PHPBB'))
+{
+	exit;
+}
+
+/**
+ * The EventDispatcherInterface is the central point of Symfony's event listener system.
+ *
+ * Listeners are registered on the manager and events are dispatched through the
+ * manager.
+ *
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ * @author  Bernhard Schussek <bschussek@gmail.com>
+ * @author  Fabien Potencier <fabien@symfony.com>
+ * @author  Jordi Boggiano <j.boggiano@seld.be>
+ * @author  Jordan Alliot <jordan.alliot@gmail.com>
+ */
+class phpbb_event_dispatcher
+{
+	private $listeners = array();
+	private $sorted = array();
+
+	/**
+	 * @see EventDispatcherInterface::dispatch
+	 *
+	 * @api
+	 */
+	public function dispatch($event_name, phpbb_event $event = null)
+	{
+		if (!isset($this->listeners[$event_name])) {
+			return;
+		}
+
+		if (null === $event) {
+			$event = new phpbb_event();
+		}
+
+		$event->set_dispatcher($this);
+		$event->set_name($event_name);
+
+		$this->do_dispatch($this->get_listeners($event_name), $event_name, $event);
+	}
+
+	/**
+	 * @see EventDispatcherInterface::get_listeners
+	 */
+	public function get_listeners($event_name = null)
+	{
+		if (null !== $event_name) {
+			if (!isset($this->sorted[$event_name])) {
+				$this->sort_listeners($event_name);
+			}
+
+			return $this->sorted[$event_name];
+		}
+
+		foreach (array_keys($this->listeners) as $event_name) {
+			if (!isset($this->sorted[$event_name])) {
+				$this->sort_listeners($event_name);
+			}
+		}
+
+		return $this->sorted;
+	}
+
+	/**
+	 * @see EventDispatcherInterface::has_listeners
+	 */
+	public function has_listeners($event_name = null)
+	{
+		return (Boolean) count($this->get_listeners($event_name));
+	}
+
+	/**
+	 * @see EventDispatcherInterface::add_listener
+	 *
+	 * @api
+	 */
+	public function add_listener($event_name, $listener, $priority = 0)
+	{
+		$this->listeners[$event_name][$priority][] = $listener;
+		unset($this->sorted[$event_name]);
+	}
+
+	/**
+	 * @see EventDispatcherInterface::remove_listener
+	 */
+	public function remove_listener($event_name, $listener)
+	{
+		if (!isset($this->listeners[$event_name])) {
+			return;
+		}
+
+		foreach ($this->listeners[$event_name] as $priority => $listeners) {
+			if (false !== ($key = array_search($listener, $listeners))) {
+				unset($this->listeners[$event_name][$priority][$key], $this->sorted[$event_name]);
+			}
+		}
+	}
+
+	/**
+	 * @see EventDispatcherInterface::add_subscriber
+	 *
+	 * @api
+	 */
+	public function add_subscriber(phpbb_event_subscriber_interface $subscriber)
+	{
+		foreach ($subscriber->get_subscribed_events() as $event_name => $params) {
+			if (is_string($params)) {
+				$this->add_listener($event_name, array($subscriber, $params));
+			} elseif (is_string($params[0])) {
+				$this->add_listener($event_name, array($subscriber, $params[0]), $params[1]);
+			} else {
+				foreach ($params as $listener) {
+					$this->add_listener($event_name, array($subscriber, $listener[0]), isset($listener[1]) ? $listener[1] : 0);
+				}
+			}
+		}
+	}
+
+	/**
+	 * @see EventDispatcherInterface::remove_subscriber
+	 */
+	public function remove_subscriber(phpbb_event_subscriber_interface $subscriber)
+	{
+		foreach ($subscriber->get_subscribed_events() as $event_name => $params) {
+			if (is_array($params) && is_array($params[0])) {
+				foreach ($params as $listener) {
+					$this->remove_listener($event_name, array($subscriber, $listener[0]));
+				}
+			} else {
+				$this->remove_listener($event_name, array($subscriber, is_string($params) ? $params : $params[0]));
+			}
+		}
+	}
+
+	/**
+	 * Triggers the listeners of an event.
+	 *
+	 * This method can be overridden to add functionality that is executed
+	 * for each listener.
+	 *
+	 * @param array[callback] $listeners The event listeners.
+	 * @param string $event_name The name of the event to dispatch.
+	 * @param Event $event The event object to pass to the event handlers/listeners.
+	 */
+	protected function do_dispatch($listeners, $event_name, phpbb_event $event)
+	{
+		foreach ($listeners as $listener) {
+			call_user_func($listener, $event);
+			if ($event->is_propagation_stopped()) {
+				break;
+			}
+		}
+	}
+
+	/**
+	 * Sorts the internal list of listeners for the given event by priority.
+	 *
+	 * @param string $event_name The name of the event.
+	 */
+	private function sort_listeners($event_name)
+	{
+		$this->sorted[$event_name] = array();
+
+		if (isset($this->listeners[$event_name])) {
+			krsort($this->listeners[$event_name]);
+			$this->sorted[$event_name] = call_user_func_array('array_merge', $this->listeners[$event_name]);
+		}
+	}
+}

phpBB/includes/event/dispatcher_interface.php

@@ -0,0 +1,96 @@
+<?php
+/**
+*
+* @package phpBB3
+* @copyright (c) 2011 phpBB Group
+* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
+*
+*/
+
+/**
+* @ignore
+*/
+if (!defined('IN_PHPBB'))
+{
+	exit;
+}
+
+/**
+ * The EventDispatcherInterface is the central point of Symfony's event listener system.
+ * Listeners are registered on the manager and events are dispatched through the
+ * manager.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+interface phpbb_event_dispatcher_interface
+{
+	/**
+	 * Dispatches an event to all registered listeners.
+	 *
+	 * @param string $event_name The name of the event to dispatch. The name of
+	 *                          the event is the name of the method that is
+	 *                          invoked on listeners.
+	 * @param Event $event The event to pass to the event handlers/listeners.
+	 *                     If not supplied, an empty Event instance is created.
+	 *
+	 * @api
+	 */
+	function dispatch($event_name, Event $event = null);
+
+	/**
+	 * Adds an event listener that listens on the specified events.
+	 *
+	 * @param string   $event_name The event to listen on
+	 * @param callable $listener  The listener
+	 * @param integer  $priority  The higher this value, the earlier an event
+	 *                            listener will be triggered in the chain (defaults to 0)
+	 *
+	 * @api
+	 */
+	function add_listener($event_name, $listener, $priority = 0);
+
+	/**
+	 * Adds an event subscriber. The subscriber is asked for all the events he is
+	 * interested in and added as a listener for these events.
+	 *
+	 * @param EventSubscriberInterface $subscriber The subscriber.
+	 *
+	 * @api
+	 */
+	function add_subscriber(phpbb_event_subscriber_interface $subscriber);
+
+	/**
+	 * Removes an event listener from the specified events.
+	 *
+	 * @param string|array $event_name The event(s) to remove a listener from.
+	 * @param object $listener The listener object to remove.
+	 */
+	function remove_listener($event_name, $listener);
+
+	/**
+	 * Removes an event subscriber.
+	 *
+	 * @param EventSubscriberInterface $subscriber The subscriber.
+	 */
+	function remove_subscriber(phpbb_event_subscriber_interface $subscriber);
+
+	/**
+	 * Gets the listeners of a specific event or all listeners.
+	 *
+	 * @param string $event_name The name of the event.
+	 *
+	 * @return array The event listeners for the specified event, or all event
+	 *               listeners by event name.
+	 */
+	function get_listeners($event_name = null);
+
+	/**
+	 * Checks whether an event has any registered listeners.
+	 *
+	 * @param string $event_name The name of the event.
+	 *
+	 * @return Boolean TRUE if the specified event has any listeners, FALSE
+	 *                 otherwise.
+	 */
+	function has_listeners($event_name = null);
+}

phpBB/includes/event/event.php

@@ -0,0 +1,123 @@
+<?php
+/**
+*
+* @package phpBB3
+* @copyright (c) 2011 phpBB Group
+* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
+*
+*/
+
+/**
+* @ignore
+*/
+if (!defined('IN_PHPBB'))
+{
+	exit;
+}
+
+/**
+ * Event is the base class for classes containing event data.
+ *
+ * This class contains no event data. It is used by events that do not pass
+ * state information to an event handler when an event is raised.
+ *
+ * You can call the method stop_propagation() to abort the execution of
+ * further listeners in your event listener.
+ *
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ * @author  Bernhard Schussek <bschussek@gmail.com>
+ */
+class phpbb_event
+{
+	/**
+	 * @var Boolean Whether no further event listeners should be triggered
+	 */
+	private $propagation_stopped = false;
+
+	/**
+	 * @var EventDispatcher Dispatcher that dispatched this event
+	 */
+	private $dispatcher;
+
+	/**
+	 * @var string This event's name
+	 */
+	private $name;
+
+	/**
+	 * Returns whether further event listeners should be triggered.
+	 *
+	 * @see Event::stop_propagation
+	 * @return Boolean Whether propagation was already stopped for this event.
+	 *
+	 * @api
+	 */
+	public function is_propagation_stopped()
+	{
+		return $this->propagation_stopped;
+	}
+
+	/**
+	 * Stops the propagation of the event to further event listeners.
+	 *
+	 * If multiple event listeners are connected to the same event, no
+	 * further event listener will be triggered once any trigger calls
+	 * stop_propagation().
+	 *
+	 * @api
+	 */
+	public function stop_propagation()
+	{
+		$this->propagation_stopped = true;
+	}
+
+	/**
+	 * Stores the EventDispatcher that dispatches this Event
+	 *
+	 * @param EventDispatcher $dispatcher
+	 *
+	 * @api
+	 */
+	public function set_dispatcher(phpbb_event_dispatcher $dispatcher)
+	{
+		$this->dispatcher = $dispatcher;
+	}
+
+	/**
+	 * Returns the EventDispatcher that dispatches this Event
+	 *
+	 * @return EventDispatcher
+	 *
+	 * @api
+	 */
+	public function get_dispatcher()
+	{
+		return $this->dispatcher;
+	}
+
+	/**
+	 * Gets the event's name.
+	 *
+	 * @return string
+	 *
+	 * @api
+	 */
+	public function get_name()
+	{
+		return $this->name;
+	}
+
+	/**
+	 * Sets the event's name property.
+	 *
+	 * @param string $name The event name.
+	 *
+	 * @api
+	 */
+	public function set_name($name)
+	{
+		$this->name = $name;
+	}
+}

phpBB/includes/event/subscriber_interface.php

@@ -0,0 +1,50 @@
+<?php
+/**
+*
+* @package phpBB3
+* @copyright (c) 2011 phpBB Group
+* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
+*
+*/
+
+/**
+* @ignore
+*/
+if (!defined('IN_PHPBB'))
+{
+	exit;
+}
+
+/**
+ * An EventSubscriber knows himself what events he is interested in.
+ * If an EventSubscriber is added to an EventDispatcherInterface, the manager invokes
+ * {@link get_subscribed_events} and registers the subscriber as a listener for all
+ * returned events.
+ *
+ * @author  Guilherme Blanco <guilhermeblanco@hotmail.com>
+ * @author  Jonathan Wage <jonwage@gmail.com>
+ * @author  Roman Borschel <roman@code-factory.org>
+ * @author  Bernhard Schussek <bschussek@gmail.com>
+ */
+interface phpbb_event_subscriber_interface
+{
+	/**
+	 * Returns an array of event names this subscriber wants to listen to.
+	 *
+	 * The array keys are event names and the value can be:
+	 *
+	 *  * The method name to call (priority defaults to 0)
+	 *  * An array composed of the method name to call and the priority
+	 *  * An array of arrays composed of the method names to call and respective
+	 *    priorities, or 0 if unset
+	 *
+	 * For instance:
+	 *
+	 *  * array('event_name' => 'method_name')
+	 *  * array('event_name' => array('method_name', $priority))
+	 *  * array('event_name' => array(array('method_name1', $priority), array('method_name2'))
+	 *
+	 * @return array The event names to listen to
+	 */
+	static function get_subscribed_events();
+}