Events

All the components in Aurora are engineered to enable you to create decoupled, modular applications.

But sometimes you need to connect modules so that they can react to changes and actions in other modules and that can break the modularization if not done properly. To assist you in that goal, Aurora implements the PSR-14 Event Dispatcher spec.

Basically, the PSR-14 spec defines a set of interfaces used to implement an application-wide event dispatcher, its listeners and the event classes themselves.

With it you will be able to broadcast any event from any place in your application and any registered listener will receive it, no matter what it does with it after and without any coupling between the two.

Creating events

To create an event run the command:

php aurora create:event UserSignUpEvent

The above will create a file name UserSignUpEvent.php in your app/Events directory with the following structure:

<?php

declare(strict_types = 1);

namespace App\Events;

use Aurora\Events\EventInterface;

class UserSignUpEvent implements EventInterface {

    # Add your event logic here
}

As you can see, the event is at this point an empty object; depending on the type of event you may want to create properties and methods accordingly.

Creating listeners

There are two ways of listening for an event.

The first is by just using a Closure for the listener:

use use Psr\Event\EventDispatcherInterface;
use App\Events\TestEvent;

...

$dispatcher = resolve(EventDispatcherInterface::class);
$dispatcher->listen(UserSignUpEvent::class, function($event) {
    # Add your listener logic here
});

Another, more modular way involves creating a listener. To do so, you can use the following command:

php aurora create:listener UserSignUpListener

This will create a UserSignUpListener.php file in the app/Events directory with the contents:

<?php

declare(strict_types = 1);

namespace App\Events;

use Aurora\Events\ListenerInterface;

class UserSignUpListener implements ListenerInterface {

    public function handle(object $event): void {
        # Add your listener logic here
    }
}

In this case you must place your handling logic in the handle method.

To register the listener, just call:

$dispatcher = resolve(EventDispatcherInterface::class);
$dispatcher->listen(UserSignUpEvent::class, new UserSignUpListener());

Broadcasting events

To broadcast an event, just create a new instance of your event and call the dispatch method on the dispatcher:

$event = new UserSignUpEvent();
$dispatcher = resolve(EventDispatcherInterface::class);
$dispatcher->dispatch($event);

All the registered listeners will receive the event signal. As the spec goes, if the event implements the StoppableEventInterface interface it would be possible to stop the propagation of the event to the other listeners.

Next up, the Namespaces map.