phpgears / event
Event handling
Requires
- php: ^7.1
- myclabs/deep-copy: ^1.8
- phpgears/dto: ~0.3.1
Requires (Dev)
- brainmaestro/composer-git-hooks: ^2.8
- friendsofphp/php-cs-fixer: ^2.16
- infection/infection: ^0.13|^0.15
- overtrue/phplint: ^1.2
- phpmd/phpmd: ^2.8
- phpstan/extension-installer: ^1.0.3
- phpstan/phpstan: ^0.12
- phpstan/phpstan-deprecation-rules: ^0.12
- phpstan/phpstan-strict-rules: ^0.12
- phpunit/phpunit: ^7.5|^8.0
- povils/phpmnd: ^2.1
- roave/security-advisories: dev-master
- sebastian/phpcpd: ^4.0
- squizlabs/php_codesniffer: ^3.5
- thecodingmachine/phpstan-strict-rules: ^0.12
README
Event
Event base classes and handling interfaces
This package only provides the building blocks to events
Installation
Composer
composer require phpgears/event
Usage
Require composer autoload file
require './vendor/autoload.php';
Events
Events are DTOs that carry all the information of an already happened situation
You can create your own by implementing Gears\Event\Event
or extending from Gears\Event\AbstractEvent
which ensures event immutability and payload and metadata is composed only of scalar values which is a very interesting capability. AbstractEvent has a private constructor forcing you to create events using occurred static method on your named constructors
use Gears\Event\AbstractEvent; class CreateUserEvent extends AbstractEvent { public static function fromPersonalData( string $name, string lastname, \DateTimeImmutable $birthDate ): self { return static::occurred([ 'name' => $name, 'lastname' => $lastname, 'birthDate' => $birthDate->format('U'), ]); } }
In case of a event without any payload you could extend Gears\Event\AbstractEmptyEvent
use Gears\Event\AbstractEvent; class CreateUserEvent extends AbstractEmptyEvent { public static function instance(): self { return self::occurred(); } }
Collection
Events can be grouped into iterables implementing Gears\Event\EventCollection
objects, Gears\Event\EventArrayCollection
and Gears\Event\EventIteratorCollection
are provided accepting only instances of Gears\Event\Event
Async events
Having event assuring all of its payload is composed only of scalar values proves handy when you want to delegate event handling to a message queue system such as RabbitMQ, Gearman or Apache Kafka, serializing/deserializing scalar values is trivial in any format and language
Asynchronous behaviour must be implemented at EventBus level, event bus must be able to identify async events (a map of events, implementing an interface, by a payload parameter, ...) and enqueue them
If you want to have asynchronous behaviour on your EventBus have a look phpgears/event-async, there you'll find all the necessary pieces to start your async event bus
Handlers
Events are handed over to implementations of Gears\Event\EventHandler
, available in this package is AbstractEventHandler
which verifies the type of the event so you can focus only on implementing the handling logic
class CreateUserEventHandler extends AbstractEventHandler { protected function getSupportedEventType(): string { return CreateUserEvent::class; } protected function handleEvent(Event $event): void { /* @var CreateUserEvent $event */ $user = new User( $event->getName(), $event->getLastname(), $event->getBirthDate() ); [...] } }
Have a look at phpgears/dto fo a better understanding of how events are built out of DTOs and how they hold their payload
Event Bus
Only Gears\Event\EventBus
interface is provided, you can easily use any of the good bus libraries available out there by simply adding an adapter layer
Implementations
Event bus implementations currently available
- phpgears/event-symfony-messenger uses Symfony's Messenger
- phpgears/event-symfony-event-dispatcher uses Symfony's Event Dispatcher
Contributing
Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before.
See file CONTRIBUTING.md
License
See file LICENSE included with the source code for a copy of the license terms.