Add usage examples to readme

README.md

@@ -9,6 +9,65 @@
 ## Details
 The [PSR-14][] standard provides interfaces used for dispatching events. But what of events themselves?
 How can a consumer of the dispatcher (i.e. the emitter) interoperate with the handler, if they have no agreement
-on what an event may look like? 
+on what an event may look like? This package aims to provide interfaces that could facilitate the interoperability
+of events that are identified by event name.
+
+## Usage
+### Basic Features
+In essence, an event is but a map of parameters associated with a name.
+
+```php
+<?php
+use Dhii\Events\Event\StoppableEventFactoryInterface;
+
+/* @var $factory StoppableEventFactoryInterface */
+$event = $factory->make('my_event', ['key' => 'value']);
+echo $event->getName(); // 'my_event'
+echo $event->getParam('key'); //  'value'
+
+$params = $event->getParams();
+var_dump($params); // ['key' => 'value']
+
+$params['hello'] = 'world';
+$event->setParams($params);
+echo $event->getParam('hello'); // 'world'
+?>
+```
+
+### With PSR-14
+Evemts cam be dispatched using a standards-compliant event dispatcher.
+This example requires the already included [`dhii/event-dispatcher-interface`][] package.
+```php
+<?php
+use Psr\EventDispatcher\EventDispatcherInterface;
+use Dhii\Events\Event\EventInterface;
+use Dhii\Events\Event\StoppableEventFactoryInterface;
+use Dhii\Events\Listener\AddListenerCapableInterface;
+
+/* @var $dispatcher EventDispatcherInterface */
+/* @var $factory StoppableEventFactoryInterface */
+/* @var $listenerMap AddListenerCapableInterface */
+
+// First listener will change a value and stop propagation
+$listenerMap->addListener('my_event', function (EventInterface $event) {
+    $params = $event->getParams();
+    $params['key'] = 'other_value';
+    $event->setParams($params);
+    $event->stopPropagation();
+}, 1);
+
+// Second listener is never run, therefore the value does not change again
+$listenerMap->addListener('my_event', function (EventInterface $event) {
+    $params = $event->getParams();
+    $params['key'] = 'yet another value';
+    $event->setParams($params);
+}, 2);
+
+$event = $factory->make('my_event', ['key' => 'value']);
+$dispatcher->dispatch($event);
+echo $event->getParam('key'); // 'other_value'
+?>
+```
 
 [PSR-14]: https://www.php-fig.org/psr/psr-14/
+[`dhii/event-dispatcher-interface`]: https://packagist.org/packages/dhii/event-dispatcher-interface