1<p align="center"> 2 <img src="https://static.hoa-project.net/Image/Hoa.svg" alt="Hoa" width="250px" /> 3</p> 4 5--- 6 7<p align="center"> 8 <a href="https://travis-ci.org/hoaproject/event"><img src="https://img.shields.io/travis/hoaproject/event/master.svg" alt="Build status" /></a> 9 <a href="https://coveralls.io/github/hoaproject/event?branch=master"><img src="https://img.shields.io/coveralls/hoaproject/event/master.svg" alt="Code coverage" /></a> 10 <a href="https://packagist.org/packages/hoa/event"><img src="https://img.shields.io/packagist/dt/hoa/event.svg" alt="Packagist" /></a> 11 <a href="https://hoa-project.net/LICENSE"><img src="https://img.shields.io/packagist/l/hoa/event.svg" alt="License" /></a> 12</p> 13<p align="center"> 14 Hoa is a <strong>modular</strong>, <strong>extensible</strong> and 15 <strong>structured</strong> set of PHP libraries.<br /> 16 Moreover, Hoa aims at being a bridge between industrial and research worlds. 17</p> 18 19# Hoa\Event 20 21[![Help on IRC](https://img.shields.io/badge/help-%23hoaproject-ff0066.svg)](https://webchat.freenode.net/?channels=#hoaproject) 22[![Help on Gitter](https://img.shields.io/badge/help-gitter-ff0066.svg)](https://gitter.im/hoaproject/central) 23[![Documentation](https://img.shields.io/badge/documentation-hack_book-ff0066.svg)](https://central.hoa-project.net/Documentation/Library/Event) 24[![Board](https://img.shields.io/badge/organisation-board-ff0066.svg)](https://waffle.io/hoaproject/event) 25 26This library allows to use events and listeners in PHP. This is an observer 27design-pattern implementation. 28 29[Learn more](https://central.hoa-project.net/Documentation/Library/Event). 30 31## Installation 32 33With [Composer](https://getcomposer.org/), to include this library into 34your dependencies, you need to 35require [`hoa/event`](https://packagist.org/packages/hoa/event): 36 37```sh 38$ composer require hoa/event '~1.0' 39``` 40 41For more installation procedures, please read [the Source 42page](https://hoa-project.net/Source.html). 43 44## Testing 45 46Before running the test suites, the development dependencies must be installed: 47 48```sh 49$ composer install 50``` 51 52Then, to run all the test suites: 53 54```sh 55$ vendor/bin/hoa test:run 56``` 57 58For more information, please read the [contributor 59guide](https://hoa-project.net/Literature/Contributor/Guide.html). 60 61## Quick usage 62 63We propose a quick overview of how to use events and listeners. 64 65### Events 66 67An event is: 68 * **Asynchronous** when registering, because the observable may not exist yet 69 while observers start to observe, 70 * **Anonymous** when using, because the observable has no idea how many and 71 what observers are observing, 72 * It aims at a **large** diffusion of data through isolated components. 73 Wherever is the observable, we can observe its data. 74 75In Hoa, an event channel has the following form: 76`hoa://Event/LibraryName/AnId:pseudo-class#anAnchor`. For instance, the 77`hoa://Event/Exception` channel contains all exceptions that have been thrown. 78The `hoa://Event/Stream/StreamName:close-before` contains all streams that are 79about to close. Thus, the following example will observe all thrown exceptions: 80 81```php 82Hoa\Event\Event::getEvent('hoa://Event/Exception')->attach( 83 function (Hoa\Event\Bucket $bucket) { 84 var_dump( 85 $bucket->getSource(), 86 $bucket->getData() 87 ); 88 } 89); 90``` 91 92Because `attach` expects a callable and because Hoa's callable implementation is 93smart, we can directly attach a stream to an event, like: 94 95```php 96Hoa\Event\Event::getEvent('hoa://Event/Exception')->attach( 97 new Hoa\File\Write('Foo.log') 98); 99``` 100 101This way, all exceptions will be printed on the `Foo.log` file. 102 103### Listeners 104 105Contrary to an event, a listener is: 106 * **Synchronous** when registering, because the observable must exist before 107 observers can observe, 108 * **Identified** when using, because the observable knows how many observers 109 are observing, 110 * It aims at a **close** diffusion of data. The observers must have an access 111 to the observable to observe. 112 113The `Hoa\Event\Listenable` interface requires the `on` method to be present to 114register a listener to a listener ID. For instance, the following example 115listens the `message` listener ID, i.e. when a message is received by the 116WebSocket server, the closure is executed: 117 118```php 119$server = new Hoa\Websocket\Server(…); 120$server->on('message', function (Hoa\Event\Bucket $bucket) { 121 var_dump( 122 $bucket->getSource(), 123 $bucket->getData() 124 ); 125}); 126``` 127 128## Documentation 129 130The 131[hack book of `Hoa\Event`](https://central.hoa-project.net/Documentation/Library/Event) contains 132detailed information about how to use this library and how it works. 133 134To generate the documentation locally, execute the following commands: 135 136```sh 137$ composer require --dev hoa/devtools 138$ vendor/bin/hoa devtools:documentation --open 139``` 140 141More documentation can be found on the project's website: 142[hoa-project.net](https://hoa-project.net/). 143 144## Getting help 145 146There are mainly two ways to get help: 147 148 * On the [`#hoaproject`](https://webchat.freenode.net/?channels=#hoaproject) 149 IRC channel, 150 * On the forum at [users.hoa-project.net](https://users.hoa-project.net). 151 152## Contribution 153 154Do you want to contribute? Thanks! A detailed [contributor 155guide](https://hoa-project.net/Literature/Contributor/Guide.html) explains 156everything you need to know. 157 158## License 159 160Hoa is under the New BSD License (BSD-3-Clause). Please, see 161[`LICENSE`](https://hoa-project.net/LICENSE) for details. 162