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.