First commit

.gitignore

@@ -0,0 +1,5 @@
+phpunit.xml
+vendor
+composer.lock
+composer.phar
+

LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2012 Jeremy Mikola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,138 @@
+# WildcardEventDispatcher
+
+This library implements an event dispatcher, based on [Symfony2's interface][],
+with wildcard syntax inspired by AMQP topic exchanges. Listeners may be bound to
+a wildcard pattern and be notified if a dispatched event's name matches that
+pattern. Literal event name matching is still supported.
+
+  [Symfony2's interface]: https://github.com/symfony/EventDispatcher
+
+## Usage ##
+
+WildcardEventDispatcher implements EventDispatcherInterface and may be used as
+you would Symfony2's standard EventDispatcher:
+
+```php
+<?php
+
+use Jmikola\WildcardEventDispatcher\WildcardEventDispatcher;
+use Symfony\Component\EventDispatcher\Event;
+
+$dispatcher = new WildcardEventDispatcher();
+$dispatcher->addListener('core.*', function(Event $e) {
+    echo $e->getName();
+});
+$dispatcher->dispatch('core.request');
+
+// "core.request" will be printed
+```
+
+Internally, WildcardEventDispatcher actually [composes][] an
+EventDispatcherInterface instance, which it relies upon for event handling. By
+default, WildcardEventDispatcher will construct an EventDispatcher object for
+internal use, but you may specify a particular EventDispatcherInterface instance
+to wrap in the constructor:
+
+```php
+<?php
+
+use Jmikola\WildcardEventDispatcher\WildcardEventDispatcher;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+
+$dispatcher = new WildcardEventDispatcher(new EventDispatcher());
+```
+
+  [composes]: http://en.wikipedia.org/wiki/Object_composition
+
+## Wildcard Syntax ##
+
+### Single-word Wildcard ###
+
+Consider the scenario where the same listener is defined for multiple events,
+all of which share a common prefix:
+
+```php
+<?php
+
+$coreListener = function(Event $e) {};
+
+$dispatcher = new WildcardEventDispatcher();
+$dispatcher->addListener('core.exception', $coreListener);
+$dispatcher->addListener('core.request', $coreListener);
+$dispatcher->addListener('core.response', $coreListener);
+```
+
+These event names all consist of two dot-separated words. This concept of a word
+will be important in understanding how wildcard patterns apply.
+
+In this example, the listener is responsible for observing all `core` events in
+the application. Let's suppose it needs to log some details about these events
+to an external server. We can refactor multiple `addListener()` calls by
+using the single-word `*` wildcard:
+
+```php
+<?php
+
+$coreListener = function(Event $e) {};
+
+$dispatcher = new WildcardEventDispatcher();
+$dispatcher->addListener('core.*', $coreListener);
+```
+
+The listener will now observe all events named `core` or starting with `core.`
+and followed by another word. The matching of `core` alone may not make sense,
+but this is implemented in order to be consistent with AMQP. A trailing `*`
+after a non-empty sequence may match the preceding sequence sans `.*`.
+
+### Multi-word Wildcard ###
+
+Suppose there was a `core` event in your application named `core.foo.bar`. The
+aforementioned `core.*` pattern would not catch this event. You could use:
+
+```php
+<?php
+
+$coreListener = function(Event $e) {};
+
+$dispatcher = new WildcardEventDispatcher();
+$dispatcher->addListener('core.*.*', $coreListener);
+```
+
+This syntax would match `core.foo` and `core.foo.bar`, but `core` would no
+longer be matched (assuming there was such an event).
+
+The multi-word `#` wildcard might be more appropriate here:
+
+```php
+<?php
+
+$coreListener = function(Event $e) {};
+
+$dispatcher = new WildcardEventDispatcher();
+$dispatcher->addListener('core.#', $coreListener);
+```
+
+Suppose there was also an listener in the application that needed to listen on
+_all_ events in the application. The multi-word `#` wildcard could be used:
+
+```php
+<?php
+
+$allListener = function(Event $e) {};
+
+$dispatcher = new WildcardEventDispatcher();
+$dispatcher->addListener('#', $allListener);
+```
+
+### Additional Wildcard Documentation ###
+
+When in doubt, the unit tests for `ListenerPattern` are a good resource for
+inferring how wildcards will be interpreted. This library aims to mimic the
+behavior of AMQP topic wildcards completely, but there may be shortcomings.
+
+Documentation for actual AMQP syntax may be found in the following packages:
+
+ * [ActiveMQ](http://activemq.apache.org/wildcards.html)
+ * [HornetQ](http://docs.jboss.org/hornetq/2.2.5.Final/user-manual/en/html/wildcard-syntax.html)
+ * [RabbitMQ](http://www.rabbitmq.com/faq.html#wildcards-in-topic-exchanges)
+ * [ZeroMQ](http://www.zeromq.org/whitepapers:message-matching)

composer.json

@@ -0,0 +1,19 @@
+{
+    "name": "jmikola/wildcard-event-dispatcher",
+    "type": "library",
+    "description": "Event dispatcher with support for wildcard patterns inspired by AMQP topic exchanges.",
+    "keywords": ["AMQP", "dispatcher", "event", "event dispatcher"],
+    "homepage": "https://github.com/jmikola/WildcardEventDispatcher",
+    "license": "MIT",
+    "authors": [
+        { "name": "Jeremy Mikola", "email": "jmikola@gmail.com" }
+    ],
+    "require": {
+        "php": ">=5.3.2",
+        "symfony/event-dispatcher": ">=2.0-dev,<2.2-dev"
+    },
+    "autoload": {
+        "psr-0": { "Jmikola\\WildcardEventDispatcher": "" }
+    },
+    "target-dir": "Jmikola/WildcardEventDispatcher"
+}

phpunit.xml.dist

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<phpunit bootstrap="./tests/bootstrap.php" colors="true">
+    <testsuites>
+        <testsuite name="WildcardEventDispatcher Test Suite">
+            <directory>./tests/</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory>./</directory>
+            <exclude>
+                <directory>./tests</directory>
+            </exclude>
+        </whitelist>
+    </filter>
+</phpunit>

src/Jmikola/WildcardEventDispatcher/LazyListenerPattern.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Jmikola\WildcardEventDispatcher;
+
+class LazyListenerPattern extends ListenerPattern
+{
+    protected $listenerProvider;
+
+    /**
+     * Constructor.
+     *
+     * The $listenerProvider argument should be a callback which, when invoked,
+     * returns the listener callback.
+     *
+     * @param string   $eventPattern
+     * @param callback $listenerProvider
+     * @param integer  $priority
+     * @throws InvalidArgumentException if the listener provider is not a callback
+     */
+    public function __construct($eventPattern, $listenerProvider, $priority = 0)
+    {
+        if (!is_callable($listenerProvider)) {
+            throw new \InvalidArgumentException('Listener provider argument must be a callback');
+        }
+
+        parent::__construct($eventPattern, null, $priority);
+
+        $this->listenerProvider = $listenerProvider;
+    }
+
+    /**
+     * Get the pattern listener, initializing it lazily from its provider.
+     *
+     * @return callback
+     */
+    public function getListener()
+    {
+        if (!isset($this->listener) && isset($this->listenerProvider)) {
+            $this->listener = call_user_func($this->listenerProvider);
+            unset($this->listenerProvider);
+        }
+
+        return $this->listener;
+    }
+}

src/Jmikola/WildcardEventDispatcher/ListenerPattern.php

@@ -0,0 +1,119 @@
+<?php
+
+namespace Jmikola\WildcardEventDispatcher;
+
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
+
+class ListenerPattern
+{
+    protected $eventPattern;
+    protected $events = array();
+    protected $listener;
+    protected $priority;
+    protected $regex;
+
+    private static $replacements = array(
+        // Trailing single-wildcard with separator prefix
+        '/\\\\\.\\\\\*$/'     => '(?:\.\w+)?',
+        // Single-wildcard with separator prefix
+        '/\\\\\.\\\\\*/'      => '(?:\.\w+)',
+        // Single-wildcard without separator prefix
+        '/(?<!\\\\\.)\\\\\*/' => '(?:\w+)',
+        // Multi-wildcard with separator prefix
+        '/\\\\\.#/'           => '(?:\.\w+)*',
+        // Multi-wildcard without separator prefix
+        '/(?<!\\\\\.)#/'      => '(?:|\w+(?:\.\w+)*)',
+    );
+
+    /**
+     * Constructor.
+     *
+     * @param string   $eventPattern
+     * @param callback $listener
+     * @param integer  $priority
+     */
+    public function __construct($eventPattern, $listener, $priority = 0)
+    {
+        $this->eventPattern = $eventPattern;
+        $this->listener = $listener;
+        $this->priority = $priority;
+        $this->regex = $this->createRegex($eventPattern);
+    }
+
+    /**
+     * Get the event pattern.
+     *
+     * @return string
+     */
+    public function getEventPattern()
+    {
+        return $this->eventPattern;
+    }
+
+    /**
+     * Get the listener.
+     *
+     * @return callback
+     */
+    public function getListener()
+    {
+        return $this->listener;
+    }
+
+    /**
+     * Adds this pattern's listener to an event.
+     *
+     * @param EventDispatcherInterface $dispatcher
+     * @param string                   $eventName
+     */
+    public function bind(EventDispatcherInterface $dispatcher, $eventName)
+    {
+        if (isset($this->events[$eventName])) {
+            return;
+        }
+
+        $dispatcher->addListener($eventName, $this->getListener(), $this->priority);
+        $this->events[$eventName] = true;
+    }
+
+    /**
+     * Removes this pattern's listener from all events to which it was
+     * previously added.
+     *
+     * @param EventDispatcherInterface $dispatcher
+     */
+    public function unbind(EventDispatcherInterface $dispatcher)
+    {
+        foreach ($this->events as $eventName => $_) {
+            $dispatcher->removeListener($eventName, $this->getListener());
+        }
+
+        $this->events = array();
+    }
+
+    /**
+     * Tests if this pattern matches and event name.
+     *
+     * @param string $eventName
+     * @return boolean
+     */
+    public final function test($eventName)
+    {
+        return (boolean) preg_match($this->regex, $eventName);
+    }
+
+    /**
+     * Transforms an event pattern into a regular expression.
+     *
+     * @param string $eventPattern
+     * @return string
+     */
+    private function createRegex($eventPattern)
+    {
+        return sprintf('/^%s$/', preg_replace(
+            array_keys(self::$replacements),
+            array_values(self::$replacements),
+            preg_quote($eventPattern, '/')
+        ));
+    }
+}