docs: Provides documentation of all functionality

Author: weierophinney

README.md

@@ -13,3 +13,7 @@ Run the following to install this library:
 ```bash
 $ composer require phly/phly-event-dispatcher
 ```
+
+## Documentation
+
+Documentation is available in the [docs/book/](docs/book/) tree.

docs/book/dispatcher.md

@@ -0,0 +1,72 @@
+# The EventDispatcher
+
+`Phly\EventDispatcher\EventDispatcher` provides a
+`Psr\EventDispatcher\EventDispatcherInterface` implementation. It accepts a 
+`Psr\EventDispatcher\ListenerProviderInterface` to its constructor, and, when
+dispatching events, queries the provider for listeners to notify.
+
+At its most basic, usage looks like this:
+
+```php
+use Phly\EventDispatcher\EventDispatcher;
+use Phly\EventDispatcher\ListenerProvider\AttachableListenerProvider;
+
+$provider = new AttachableListenerProvider();
+$provider->listen(SomeEvent::class, function (SomeEvent $event) : void {
+    // do something with the event
+});
+
+$dispatcher = new EventDispatcher($provider);
+
+$dispatcher->dispatch(new SomeEvent());
+```
+
+## ErrorEmittingDispatcher
+
+Occasionally, listeners may raise exceptions. PSR-14 indicates that these should
+be thrown verbatim from the dispatcher. However, what if you'd like to trigger
+an event when an error occurs, such as occurs with Node's event loop?
+
+To handle this scenario, the library provides `Phly\EventDispatcher\ErrorEmittingDispatcher`.
+This implementation catches any exception or throwable, and then casts it to a
+special `Phly\EventDispatcher\ErrorEvent`, which it then  dispatches. This
+allows you to add listeners to the `ErrorEvent` class in order to receive
+notifications about errors!
+
+The `ErrorEvent` exposes three methods for retrieving information about the
+error:
+
+- `getEvent()` will return the original event that was dispatched when the error
+  was caught.
+- `getListener()` will return the listener that raised the error.
+- `getThrowable() `will return the throwable that was raised.
+
+As an example:
+
+```php
+use Phly\EventDispatcher\ErrorEmittingDispatcher;
+use Phly\EventDispatcher\ErrorEvent;
+use Phly\EventDispatcher\ListenerProvider\AttachableListenerProvider;
+use Psr\Logger\LoggerInterface;
+
+$provider = new AttachableListenerProvider();
+$provider->listen(SomeEvent::class, function (SomeEvent $event) : void {
+    // Raise an exception
+    throw new RuntimeException('Could not handle the event!');
+});
+
+// @var LoggerInterface $logger
+$provider->listen(ErrorEvent::class, function (ErrorEvent $event) use ($logger) : void {
+    $logger->error('Error processing event of type {type}: {message}', [
+        'type'    => get_class($event->getEvent()),
+        'message' => $event->getThrowable()->getMessage(),
+    ]);
+});
+
+$dispatcher = new EventDispatcher($provider);
+
+$dispatcher->dispatch(new SomeEvent());
+```
+
+The exception will still be thrown; however, it will also be logged, due to our
+`ErrorEvent` listener!

docs/book/intro.md

@@ -1,3 +1,15 @@
-# event-dispatcher
+# phly-event-dispatcher
 
-This component provides ...
+This component provides a [PSR-14](https://github.com/php-fig/fig-standards/blob/eab4613522cfb585ed7fdc13e501f78220886a02/proposed/event-dispatcher.md)
+implementation, specifically implementing each of:
+
+- `Psr\EventDispatcher\EventDispatcherInterface`
+- `Psr\EventDispatcher\ListenerProviderInterface`
+
+The package provides a standard event dispatcher, as well as one that provides
+error handling. It also provides a number of additional listener provider
+interfaces, as well as implementations, spanning basic attachment, prioritized
+attachment, reflection-based attachment, and more.
+
+On top of these facilities, it provides a number of additional features,
+including lazy-loading listeners.

docs/book/lazy-listeners.md

@@ -0,0 +1,31 @@
+# Lazy Listeners
+
+To save on the cost of loading potentially expensive objects, you may want to
+_lazy load_ listeners. For the purposes of this library, lazy loading refers
+specifically to retrieving a listener from a [PSR-11 dependency injection
+container](https://www.php-fig.org/psr/psr-11/) at the point of listener
+invocation.
+
+The library provides `Phly\EventDispatcher\LazyListener` to facilitate such
+operations. The class has a constructor that accepts a PSR-11 container, the
+string service name to pull from the container, and, optionally, a method to
+call on that service (if none is provided, it assumes the class is invokable).
+
+As an example:
+
+```php
+$listener = new LazyListener($container, ActualListener::class);
+```
+
+## lazyListener()
+
+As a shortcut, we also provide the function
+`Phly\EventDispatcher\lazyListener()`, which accepts the same arguments as the
+`LazyListener` constructor. This is particularly useful when attaching
+listeners:
+
+```php
+use function Phly\EventManager\lazyListener;
+
+$provider->listen(lazyListener($container, ActualListener::class));
+```

docs/book/listener-providers.md

@@ -0,0 +1,167 @@
+# Listener Providers
+
+Listener providers aggregate listeners, and allow a [dispatcher](dispatcher.md)
+to retrieve all listeners capable of listening to the event it is currently
+dispatching.
+
+This library provides several additional provider interfaces, as well as
+implementations, for common listener registration patterns.
+
+## Basic listener attachment
+
+`Phly\EventDispatcher\ListenerProvider\AttachableListenerProviderInterface`
+extends `Psr\EventDispatcher\ListenerProviderInterface` and defines a very basic
+attachment pattern:
+
+```php
+public function listen(string $eventName, callable $listener) : void
+```
+
+The library provides an implementation via
+`Phly\EventDispatcher\ListenerProvider\AttachableListenerProvider`.
+
+## Positionable attachment
+
+`Phly\EventDispatcher\ListenerProvider\PositionalListenerProviderInterface`
+extends `AttachableListenerProviderInterface`, and adds the following two
+methods:
+
+```php
+public function listenAfter(string $listenerTypeToAppend, string $eventType, callable $newListener) : void;
+public function listenBefore(string $listenerTypeToPrepend, string $eventType, callable $newListener) : void;
+```
+
+In both cases, the implication is that implementations will append or prepend
+the new listener to the last or first listener that matches the type of the
+first argument.
+
+As an example,
+
+```php
+$provider->listenAfter(
+    SendMailListener::class,
+    ContactEvent::class,
+    lazyListener($container, LoggingListener::class)
+)
+```
+
+would add a new `LoggingListener` to the provider, to execute after any
+previously registered `SendMailListener` instances.
+
+> See the chapter on [lazy listeners](lazy-listeners.md) for information on the
+> `lazyListener()` function.
+
+This library does not currently provide any implementations of this interface.
+
+## Prioritized attachment
+
+`Phly\EventDispatcher\ListenerProvider\PrioritizedListenerProviderInterface`
+extends the PSR-14 `ListenerProviderInterface`, and defines a single method for
+attaching listeners:
+
+```php
+public function listen(string $eventType, callable $listener, int $priority = 1) : void;
+```
+
+Priority values are expected to follow the same behavior as `SplPriorityQueue`:
+larger values should execute first, while negative values should execute last.
+Listeners registered at the same priority should execute in the order in which
+they are attached to the provider.
+
+As an example:
+
+```php
+$provider = new PrioritizedListenerProvider();
+
+class SomeEvent
+{
+    public $counter = [];
+}
+
+$factory = function (int $index) : callable {
+    return function (object $event) use ($index) : void {
+        $event->counter[] = $index;
+    };
+};
+
+$provider->listen(SomeEvent::class, $factory(1));
+$provider->listen(SomeEvent::class, $factory(2), -100);
+$provider->listen(SomeEvent::class, $factory(3), 100);
+
+$dispatcher = new EventDispatcher($provider);
+
+var_export($dispatcher->dispatch(new SomeEvent()));
+/*
+array (
+  0 => 3,
+  1 => 1,
+  2 => 2,
+)
+*/
+```
+
+This library provides an implementation via the class
+`Phly\EventDispatcher\ListenerProvider\PrioritizedListenerProvider`.
+
+## Randomized attachment
+
+If you do not care what order listeners are called in, and, in fact, want to
+enforce that the order is random, you can use
+`Phly\EventDispatcher\ListenerProvider\RandomizedListenerProvider`. This class
+defines the same `listen()` method as the `AttachableListenerProvider` detailed
+in an earlier section, but has a `getListenersForEvent()` method that randomizes
+the order in which listeners are returned during iteration.
+
+## Reflection-based attachment
+
+Since events are objects, one way to identify if a listener can listen to a
+given event is to _reflect_ on its argument, to see what type it accepts.
+This package defines an interface for providers that can do this, via
+`Phly\EventDispatcher\ListenerProvider\ReflectableListenerProviderInterface`:
+
+```php
+public function listen(callable $listener, string $eventType = null) : void;
+```
+
+When called with a single argument, implementations are expected to use
+reflection to determine which event type(s) the listener can accept. As an
+example:
+
+```php
+$provider = new ReflectionBasedListenerProvider();
+
+class SomeEvent
+{
+}
+
+$listener = function (SomeEvent $event) : void {
+    // do something
+};
+
+$provider->listen($listener);
+
+// This will dispatch $listener:
+$dispatcher->dispatch(new SomeEvent());
+```
+
+The package provides an implementation via `Phly\EventDispatcher\ListenerProvider\ReflectionBasedListenerProvider`.
+
+## Provider aggregation
+
+You may want to allow multiple providers in your application, but still have a
+single dispatcher. `Phly\EventDispatcher\ListenerProvider\ListenerProviderAggregate`
+allows aggregating multiple providers into a single one, which will then loop
+through each to yield listeners.
+
+```php
+$nonPrioritized = new AttachableListenerProvider();
+$prioritized    = new PrioritizedListenerProvider();
+$reflected      = new ReflectionBasedListenerProvider();
+
+$provider = new ListenerProviderAggregate();
+$provider->attach($nonPrioritized);
+$provider->attach($prioritized);
+$provider->attach($reflected);
+
+$dispatcher = new EventDispatcher($provider);
+```

mkdocs.yml

@@ -1,9 +1,13 @@
 docs_dir: docs/book
 site_dir: docs/html
 pages:
-    - index.md
+    - Home: index.md
     - Introduction: intro.md
-site_name: Component Name Goes Here
+    - Reference:
+      - "Event Dispatcher": dispatcher.md
+      - "Listener Providers": listener-providers.md
+      - "Lazy Listeners": lazy-listeners.md
+site_name: 'phly-event-dispatcher'
 site_description: 'Component Description goes here'
 repo_url: 'https://github.com/phly/event-dispatcher'
-copyright: 'Copyright (c) 2018 <a href="https://www.zend.com/">Zend Technologies USA Inc.</a>'
+copyright: 'Copyright (c) <a href="https://mwop.net/">Matthew Weier O\'Phinney</a>'