# The EventManager

## Overview

`Zend_EventManager` is a component designed for the following use cases:

- Implementing simple subject/observer patterns.

- Implementing Aspect-Oriented designs.

- Implementing event-driven architectures.

The basic architecture allows you to attach and detach listeners to named events, both on a per-instance basis as well as statically; trigger events; and interrupt execution of listeners.

## Quick Start

Typically, you will compose a `Zend_EventManager_EventManager` instance in a class.

    class Foo
    {
        protected $events;

        public function events(Zend_EventManager_EventCollection $events = null)
        {
            if (null !== $events) {
                $this->events = $events;
            } elseif (null === $this->events) {
                $this->events = new Zend_EventManager_EventManager(__CLASS__);
            }
            return $this->events;
        }
    }

The above allows users to access the `EventManager` instance, or reset it with a new instance; if one does not exist, it will be lazily instantiated on-demand.

An `EventManager` is really only interesting if it triggers some events. Basic triggering takes three arguments: the event name, which is usually the current function/method name; the "context", which is usually the current object instance; and the arguments, which are usually the arguments provided to the current function/method.

    class Foo
    {
        // ... assume events definition from above

        public function bar($baz, $bat = null)
        {
            $params = compact('baz', 'bat');
            $this->events()->trigger(__FUNCTION__, $this, $params);
        }
    }

In turn, triggering events is only interesting if something is listening for the event. Listeners attach to the `EventManager`, specifying a named event and the callback to notify. The callback receives a `Zend_EventManager_Event` object, which has accessors for retrieving the event name, context, and parameters. Let's add a listener, and trigger the event.

    $log = Zend_Log::factory($someConfig);
    $foo = new Foo();
    $foo->events()->attach('bar', function ($e) use ($log) {
        $event  = $e->getName();
        $target = get_class($e->getTarget());
        $params = json_encode($e->getParams());

        $log->info(sprintf(
            '%s called on %s, using params %s',
            $event,
            $target,
            $params
        ));
    });

    // Results in log message:
    $foo->bar('baz', 'bat');
    // reading: bar called on Foo, using params {"baz" : "baz", "bat" : "bat"}"

Note that the second argument to `attach()` is any valid callback; an anonymous function is shown in the example in order to keep the example self-contained. However, you could also utilize a valid function name, a functor, a string referencing a static method, or an array callback with a named static method or instance method. Again, any PHP callback is valid.

Sometimes you may want to specify listeners without yet having an object instance of the class composing an `EventManager`. The `Zend_EventManager_StaticEventManager` allows you to do this. The call to `attach` is identical to the `EventManager`, but expects an additional parameter at the beginning: a named instance. Remember the example of composing an `EventManager`, how we passed it `__CLASS__`? That value, or any strings you provide in an array to the constructor, may be used to identify an instance when using the `StaticEventManager`. As an example, we could change the above example to attach statically:

    $log = Zend_Log::factory($someConfig);
    $events = Zend_EventManager_StaticEventManager::getInstance();
    $events->attach('Foo', 'bar', function ($e) use ($log) {
        $event  = $e->getName();
        $target = get_class($e->getTarget());
        $params = json_encode($e->getParams());

        $log->info(sprintf(
            '%s called on %s, using params %s',
            $event,
            $target,
            $params
        ));
    });

    // Later, instantiate Foo:
    $foo = new Foo();

    // And we can still trigger the above event:
    $foo->bar('baz', 'bat');
    // results in log message:
    // bar called on Foo, using params {"baz" : "baz", "bat" : "bat"}"

The `EventManager` also provides the ability to detach listeners, short-circuit execution of an event either from within a listener or by testing return values of listeners, test and loop through the results returned by listeners, prioritize listeners, and more. Many of these features are detailed in the examples.

### Wildcard Listeners

Sometimes you'll want to attach the same listener to many events or to all events of a given instance -- or potentially, with the static manager, many contexts, and many events. The `EventManager` component allows for this.

#### Attaching to many events at once

    $events = new Zend_EventManager_EventManager();
    $events->attach(array('these', 'are', 'event', 'names'), $callback);

Note that if you specify a priority, that priority will be used for all events specified.

#### Attaching using the wildcard

    $events = new Zend_EventManager_EventManager();
    $events->attach('*', $callback);

Note that if you specify a priority, that priority will be used for this listener for any event triggered.

What the above specifies is that any event triggered will result in notification of this particular listener.

#### Attaching to many events at once via the StaticEventManager

    $events = Zend_EventManager_StaticEventManager::getInstance();
    // Attach to many events on the context "foo"
    $events->attach('foo', array('these', 'are', 'event', 'names'), $callback);

    // Attach to many events on the contexts "foo" and "bar"
    $events->attach(array('foo', 'bar'), array('these', 'are', 'event', 'names'), $callback);

Note that if you specify a priority, that priority will be used for all events specified.

#### Attaching to many events at once via the StaticEventManager

    $events = Zend_EventManager_StaticEventManager::getInstance();
    // Attach to all events on the context "foo"
    $events->attach('foo', '*', $callback);

    // Attach to all events on the contexts "foo" and "bar"
    $events->attach(array('foo', 'bar'), '*', $callback);

Note that if you specify a priority, that priority will be used for all events specified.

The above is specifying that for the contexts "foo" and "bar", the specified listener should be notified for any event they trigger.

## Configuration Options

### Zend_EventManager_EventManager Options

identifier

  A string or array of strings to which the given `EventManager` instance can answer when accessed via the `StaticEventManager`.

event_class

  The name of an alternate `Zend_EventManager_Event` class to use for representing events passed to listeners.

static_connections

  An instance of a Zend_EventManager_StaticEventCollection instance to use when triggering events. By default, this will use the global `Zend_EventManager_StaticEventManager` instance, but that can be overridden by passing a value to this method. A `null` value will prevent the instance from triggering any further statically attached listeners.

## Available Methods

__construct
  __construct
  null|string|int $identifier

  Constructs a new `EventManager` instance, using the given identifier, if provided, for purposes of static attachment.

setEventClass
  setEventClass
  string $class

  Provide the name of an alternate `Zend_EventManager_Event` class to use when creating events to pass to triggered listeners.

setStaticConnections
  setStaticConnections
  Zend_EventManager_StaticEventCollection $connections = null

  An instance of a Zend_EventManager_StaticEventCollection instance to use when triggering events. By default, this will use the global `Zend_EventManager_StaticEventManager` instance, but that can be overridden by passing a value to this method. A `null` value will prevent the instance from triggering any further statically attached listeners.

getStaticConnections
  getStaticConnections

  Returns the currently attached Zend_EventManager_StaticEventCollection instance, lazily retrieving the global `Zend_EventManager_StaticEventManager` instance if none is attached and usage of static listeners hasn't been disabled by passing a `null` value to setStaticConnections(). Returns either a boolean `false` if static listeners are disabled, or a StaticEventCollection instance otherwise.

trigger
  trigger
  string $event, mixed $target, mixed $argv, callback $callback

  Triggers all listeners to a named event. The recommendation is to use the current function/method name for `$event`, appending it with values such as ".pre", ".post", etc. as needed. `$context` should be the current object instance, or the name of the function if not triggering within an object. `$params` should typically be an associative array or `ArrayAccess` instance; we recommend using the parameters passed to the function/method (`compact()` is often useful here). This method can also take a callback and behave in the same way as `triggerUntil()`.

  The method returns an instance of `Zend_EventManager_ResponseCollection`, which may be used to introspect return values of the various listeners, test for short-circuiting, and more.

triggerUntil
  triggerUntil
  string $event, mixed $context, mixed $argv, callback $callback

  Triggers all listeners to a named event, just like trigger(), with the addition that it passes the return value from each listener to `$callback`; if `$callback` returns a boolean `true` value, execution of the listeners is interrupted. You can test for this using `$result->stopped()`.

attach
  attach
  string $event, callback $callback, int $priority

  Attaches `$callback` to the `Zend_EventManager_EventManager` instance, listening for the event `$event`. If a `$priority` is provided, the listener will be inserted into the internal listener stack using that priority; higher values execute earliest. (Default priority is "1", and negative priorities are allowed.)

  The method returns an instance of `Zend_Stdlib_CallbackHandler`; this value can later be passed to `detach()` if desired.

attachAggregate
  attachAggregate
  string|Zend_EventManager_ListenerAggregate $aggregate

  If a string is passed for `$aggregate`, instantiates that class. The `$aggregate` is then passed the `EventManager` instance to its `attach()` method so that it may register listeners.

  The `ListenerAggregate` instance is returned.

detach
  detach
  Zend_Stdlib_CallbackHandler $listener

  Scans all listeners, and detaches any that match `$listener` so that they will no longer be triggered.

  Returns a boolean `true` if any listeners have been identified and unsubscribed, and a boolean `false` otherwise.

detachAggregate
  detachAggregate
  Zend_EventManager_ListenerAggregate $aggregate

  Loops through all listeners of all events to identify listeners that are represented by the aggregate; for all matches, the listeners will be removed.

  Returns a boolean `true` if any listeners have been identified and unsubscribed, and a boolean `false` otherwise.

detachAggregate
  getEvents

  Returns an array of all event names that have listeners attached.

getListeners
  getListeners
  string $event

  Returns a `Zend_Stdlib_PriorityQueue` instance of all listeners attached to `$event`.

clearListeners
  clearListeners
  string $event

  Removes all listeners attached to `$event`.

prepareArgs
  prepareArgs
  array $args

  Creates an `ArrayObject` from the provided `$args`. This can be useful if you want yours listeners to be able to modify arguments such that later listeners or the triggering method can see the changes.

## Examples

### Modifying Arguments

Occasionally it can be useful to allow listeners to modify the arguments they receive so that later listeners or the calling method will receive those changed values.

As an example, you might want to pre-filter a date that you know will arrive as a string and convert it to a `DateTime` argument.

To do this, you can pass your arguments to `prepareArgs()`, and pass this new object when triggering an event. You will then pull that value back into your method.

    class ValueObject
    {
        // assume a composed event manager

        function inject(array $values)
        {
            $argv = compact('values');
            $argv = $this->events()->prepareArgs($argv);
            $this->events()->trigger(__FUNCTION__, $this, $argv);
            $date = isset($argv['values']['date']) ? $argv['values']['date'] : new DateTime('now');

            // ...
        }
    }

    $v = new ValueObject();

    $v->events()->attach('inject', function($e) {
        $values = $e->getParam('values');
        if (!$values) {
            return;
        }
        if (!isset($values['date'])) {
            $values['date'] = new DateTime('now');
            return;
        }
        $values['date'] = new Datetime($values['date']);
    });

    $v->inject(array(
        'date' => '2011-08-10 15:30:29',
    ));

### Short Circuiting

One common use case for events is to trigger listeners until either one indicates no further processing should be done, or until a return value meets specific criteria. As examples, if an event creates a Response object, it may want execution to stop.

    $listener = function($e) {
        // do some work

        // Stop propagation and return a response
        $e->stopPropagation(true);
        return $response;
    };

Alternately, we could do the check from the method triggering the event.

    class Foo implements Dispatchable
    {
        // assume composed event manager

        public function dispatch(Request $request, Response $response = null)
        {
            $argv = compact('request', 'response');
            $results = $this->events()->triggerUntil(__FUNCTION__, $this, $argv, function($v) {
                return ($v instanceof Response);
            });
        }
    }

Typically, you may want to return a value that stopped execution, or use it some way. Both `trigger()` and `triggerUntil()` return a `Zend_EventManager_ResponseCollection` instance; call its `stopped()` method to test if execution was stopped, and `last()` method to retrieve the return value from the last executed listener:

    class Foo implements Dispatchable
    {
        // assume composed event manager

        public function dispatch(Request $request, Response $response = null)
        {
            $argv = compact('request', 'response');
            $results = $this->events()->triggerUntil(__FUNCTION__, $this, $argv, function($v) {
                return ($v instanceof Response);
            });

            // Test if execution was halted, and return last result:
            if ($results->stopped()) {
                return $results->last();
            }

            // continue...
        }
    }

### Assigning Priority to Listeners

One use case for the `EventManager` is for implementing caching systems. As such, you often want to check the cache early, and save to it late.

The third argument to `attach()` is a priority value. The higher this number, the earlier that listener will execute; the lower it is, the later it executes. The value defaults to 1, and values will trigger in the order registered within a given priority.

So, to implement a caching system, our method will need to trigger an event at method start as well as at method end. At method start, we want an event that will trigger early; at method end, an event should trigger late.

Here is the class in which we want caching:

    class SomeValueObject
    {
        // assume it composes an event manager

        public function get($id)
        {
            $params = compact('id');
            $results = $this->events()->trigger('get.pre', $this, $params);

            // If an event stopped propagation, return the value
            if ($results->stopped()) {
                return $results->last();
            }

            // do some work...

            $params['__RESULT__'] = $someComputedContent;
            $this->events()->trigger('get.post', $this, $params);
        }
    }

Now, let's create a ListenerAggregate that can handle caching for us:

    class CacheListener implements Zend_EventManager_ListenerAggregate
    {
        protected $cache;

        public function __construct(Cache $cache)
        {
            $this->cache = $cache;
        }

        public function attach(Zend_EventManager_EventCollection $events)
        {
            $events->attach('get.pre', array($this, 'load'), 100);
            $events->attach('get.post', array($this, 'save'), -100);
        }

        public function load($e)
        {
            $id = get_class($e->getTarget()) . '-' . json_encode($e->getParams());
            if (false !== ($content = $this->cache->load($id))) {
                $e->stopPropagation(true);
                return $content;
            }
        }

        public function save($e)
        {
            $params  = $e->getParams();
            $content = $params['__RESULT__'];
            unset($params['__RESULT__']);

            $id = get_class($e->getTarget()) . '-' . json_encode($params);
            $this->cache->save($content, $id);
        }
    }

We can then attach the aggregate to an instance.

    $value         = new SomeValueObject();
    $cacheListener = new CacheListener($cache);
    $value->events()->attachAggregate($cacheListener);

Now, as we call `get()`, if we have a cached entry, it will be returned immediately; if not, a computed entry will be cached when we complete the method.