Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kelvinmo/f3-event-dispatcher
A PSR-14 compliant event dispatcher for the Fat-Free Framework
https://github.com/kelvinmo/f3-event-dispatcher
Last synced: 9 days ago
JSON representation
A PSR-14 compliant event dispatcher for the Fat-Free Framework
- Host: GitHub
- URL: https://github.com/kelvinmo/f3-event-dispatcher
- Owner: kelvinmo
- License: gpl-3.0
- Created: 2021-06-27T06:52:35.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-01-01T03:32:14.000Z (12 months ago)
- Last Synced: 2024-11-09T06:55:32.047Z (about 1 month ago)
- Language: PHP
- Size: 55.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: COPYING.txt
Awesome Lists containing this project
README
# Event Dispatcher for the Fat-Free Framework
This is a simple [PSR-14] compliant event dispatcher and listener provider
library for the [Fat-Free Framework][F3].
[](https://packagist.org/packages/kelvinmo/f3-event-dispatcher)
[](https://github.com/kelvinmo/f3-event-dispatcher/actions?query=workflow%3ACI)
## Requirements
- PHP 7.2 or later
- Fat-Free Framework 3.5 or later
## Installation
You can install via [Composer](http://getcomposer.org/).
```sh
composer require kelvinmo/f3-event-dispatcher
```
## Usage
### Listener Provider
The listener provider is implemented by the `\Listeners` class. `Listeners`
is a subclass of Fat-Free's `\Prefab` class.
```php
$listeners = \Listeners::instance();
```
To add a listener, call the `on()` method. The name of the event is
specified in the first parameter and the listener in the second
parameter.
As required by [PSR-14], if the name of the event is the name of a
class, then the listener will also be triggered for all subclasses
of that event class.
The listener can be a PHP callable, or a string that can be resolved
by Fat-Free's [`call()`] method
```php
// Object method
$listeners->on(FooEvent::class, 'Bar->listener');
// Static method
$listeners->on(FooEvent::class, 'Bar::listener');
// PHP callable
$listeners->on(FooEvent::class, [ $object, 'listener' ]);
// Closure
$listeners->on(FooEvent::class, function($event) {
// listener
});
```
The `on()` method also takes a third, optional parameter, specifying the
priority which the listeners should be called. Listeners are called
from the highest priority to the lowest.
```php
// Baz->listener is called first, then Bar->listener
$listeners->on(FooEvent::class, 'Bar->listener', 10);
$listeners->on(FooEvent::class, 'Baz->listener', 20);
```
You can use `Listeners` with any [PSR-14]-compliant event dispatcher.
#### Generic Events
Sometimes it is too cumbersome to create a new event class for every
single event. You can use *generic events* to group a set of related
events into a single class.
A generic event implements `GenericEventInterface` and provides the
name of the event through the `getEventName()` method.
```php
class BarEvent implements GenericEventInterface {
private $eventName;
public function __construct($eventName) {
$this->eventName = $eventName;
}
public function getEventName() {
return $this->eventName;
}
}
$listeners->on('foo', 'Baz->listener');
$event = new BarEvent('foo');
```
#### Adding Listeners via Reflection
You can also add listeners using reflection by the `map()` method. This
method takes a name or an instantiated object of a class. A listener
will be added based on a method of this class if:
1. It is a `public` method (whether or not it is also `static`)
2. The name of the method starts with `on`
3. The method takes exactly one parameter, and the parameter is type-hinted
with an event class.
The name of the event the method will listen to depends on the name of
the method. If the name of the method is the same as the short name
of the type hint of the parameter, then the name of the event is the
fully qualified name of the parameter type. Otherwise, the name of the
event is the method name converted to snake case, in which case
the event type must be a generic event (i.e. implements
`GenericEventInterface`).
```php
class TestListener {
// Will be mapped to FooEvent (with namespace)
public function onFooEvent(FooEvent $event) {
}
// Will be mapped to custom_event
// (BarEvent must implement GenericEventInterface)
public function onCustomEvent(BarEvent $event) {
}
}
$listeners = \Listeners::instance();
$listeners->map(TestListener::class);
```
### Event Dispatcher
The event dispatcher is implemented by the `\Events` class. `Events`
is a subclass of Fat-Free's `\Prefab` class.
```php
$dispatcher = \Events::instance();
```
By default, `Events` uses the `Listeners` listener provider included in this
library. To use a different listener provider, pass the provider as
an argument in the constructor.
```php
use League\Event\PrioritizedListenerRegistry;
$listenerProvider = new PrioritizedListenerRegistry();
$dispatcher = \Events::instance($listenerProvider);
```
To use the event dispatcher, call the standard PSR-14 `dispatch()` method:
```php
$dispatcher->dispatch(new FooEvent());
```
## Licence
GPL 3 or later
[PSR-14]: https://www.php-fig.org/psr/psr-14/
[F3]: https://fatfreeframework.com/
[`call()`]: https://fatfreeframework.com/3.7/base#call