aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorIvan Enderlin <ivan.enderlin@hoa-project.net>2015-11-13 08:43:08 +0100
committerIvan Enderlin <ivan.enderlin@hoa-project.net>2015-11-17 21:45:01 +0100
commit3476ff9559a1d1933333dc513d817f3d36980cb0 (patch)
treeda51624b43e3f7d856fea9f5d768488173d92859
parent76f7c2912941604af01e51e20fc3ac105b8c0e7c (diff)
downloadEvent-3476ff9559a1d1933333dc513d817f3d36980cb0.zip
Event-3476ff9559a1d1933333dc513d817f3d36980cb0.tar.gz
Event-3476ff9559a1d1933333dc513d817f3d36980cb0.tar.bz2
README: Complete description and add usage.
-rw-r--r--README.md68
1 files changed, 66 insertions, 2 deletions
diff --git a/README.md b/README.md
index ec3f155..36c8596 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,8 @@ Moreover, Hoa aims at being a bridge between industrial and research worlds.
# Hoa\Event ![state](http://central.hoa-project.net/State/Event)
-This library allows to use events and listeners in PHP.
+This library allows to use events and listeners in PHP. This is an observer
+design-pattern implementation.
## Installation
@@ -26,7 +27,70 @@ install](http://hoa-project.net/Source.html).
## Quick usage
-…
+We propose a quick overview of how to use events and listeners.
+
+### Events
+
+An event is:
+ * **Asynchronous** when registering, because the observable may not exist yet
+ while observers start to observe,
+ * **Anonymous** when using, because the observable has no idea how many and
+ what observers are observing,
+ * It aims at a **large** diffusion of data through isolated components.
+ Wherever is the observable, we can observe its data.
+
+In Hoa, an event channel has the following form:
+`hoa://Event/LibraryName/AnId:pseudo-class#anAnchor`. For instance, the
+`hoa://Event/Exception` channel contains all exceptions that have been thrown.
+The `hoa://Event/Stream/StreamName:close-before` contains all streams that are
+about to close. Thus, the following example will observe all thrown exceptions:
+
+```php
+Hoa\Event\Event::getEvent('hoa://Event/Exception')->attach(
+ function (Hoa\Event\Bucket $bucket) {
+ var_dump(
+ $bucket->getSource(),
+ $bucket->getData()
+ );
+ }
+);
+```
+
+Because `attach` expects a callable and because Hoa's callable implementation is
+smart, we can directly attach a stream to an event, like:
+
+```php
+Hoa\Event\Event::getEvent('hoa://Event/Exception')->attach(
+ new Hoa\File\Write('Foo.log')
+);
+```
+
+This way, all exceptions will be printed on the `Foo.log` file.
+
+### Listeners
+
+Contrary to an event, a listener is:
+ * **Synchronous** when registering, because the observable must exist before
+ observers can observe,
+ * **Identified** when using, because the observable knows how many observers
+ are observing,
+ * It aims at a **close** diffusion of data. The observers must have an access
+ to the observable to observe.
+
+The `Hoa\Event\Listenable` interface requires the `on` method to be present to
+register a listener to a listener ID. For instance, the following example
+listens the `message` listener ID, i.e. when a message is received by the
+WebSocket server, the closure is executed:
+
+```php
+$server = new Hoa\Websocket\Server(…);
+$server->on('message', function (Hoa\Event\Bucket $bucket) {
+ var_dump(
+ $bucket->getSource(),
+ $bucket->getData()
+ );
+});
+```
## Documentation