Event handling

0.2 2019-09-22 15:08 UTC


PHP version Latest Version License

Build Status Style Check Code Quality Code Coverage

Total Downloads Monthly Downloads


Event base classes and handling interfaces

This package only provides the building blocks to events



composer require phpgears/event


Require composer autoload file

require './vendor/autoload.php';


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();


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


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(


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


Event bus implementations currently available


Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before.

See file


See file LICENSE included with the source code for a copy of the license terms.