hoa / event
The Hoa\Event library.
Installs: 19 436 187
Dependents: 19
Suggesters: 0
Security: 0
Stars: 323
Watchers: 5
Forks: 5
Open Issues: 4
Requires
- php: >=7.1
- hoa/consistency: ~2.0
- hoa/exception: ~2.0
Requires (Dev)
- hoa/test: ~3.0
This package is auto-updated.
Last update: 2021-09-20 08:30:50 UTC
README
Hoa is a modular, extensible and
structured set of PHP libraries.
Moreover, Hoa aims at being a bridge between industrial and research worlds.
Hoa\Event
This library allows to use events and listeners in PHP. This is an observer design-pattern implementation.
Installation
With Composer, to include this library into
your dependencies, you need to
require hoa/event
:
$ composer require hoa/event '~2.0'
For more installation procedures, please read the Source page.
Testing
Before running the test suites, the development dependencies must be installed:
$ composer install
Then, to run all the test suites:
$ vendor/bin/hoa test:run
For more information, please read the contributor guide.
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:
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:
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:
$server = new Hoa\Websocket\Server(…); $server->on('message', function (Hoa\Event\Bucket $bucket) { var_dump( $bucket->getSource(), $bucket->getData() ); });
Documentation
The
hack book of Hoa\Event
contains
detailed information about how to use this library and how it works.
To generate the documentation locally, execute the following commands:
$ composer require --dev hoa/devtools $ vendor/bin/hoa devtools:documentation --open
More documentation can be found on the project's website: hoa-project.net.
Getting help
There are mainly two ways to get help:
- On the
#hoaproject
IRC channel, - On the forum at users.hoa-project.net.
Contribution
Do you want to contribute? Thanks! A detailed contributor guide explains everything you need to know.
License
Hoa is under the New BSD License (BSD-3-Clause). Please, see
LICENSE
for details.