The Essential Framework is compatible with PSR-14, which means that all event dispatchers implementing PSR-14 are compatible with the framework. By default, the framework uses the devcoder-xyz/php-event-dispatcher
library for event handling. You can refer to the documentation here for more details on how to use this library.
Now, let's explore how events are handled within the framework and how you can integrate your event listeners and subscribers.
Event configuration in the Essential Framework is managed through the listeners.php
file located in the /config
directory. This file allows you to specify event-to-listener mappings for your application.
Here's an example of event configuration in the framework, demonstrating two ways to define event listeners:
- Single Listener:
return [
\App\Event\ExampleEvent::class => \App\Listeners\ExampleListener::class
];
- Multiple Listeners (Array):
return [
\App\Event\ExampleEvent::class => [
\App\Listeners\ExampleListener::class,
\App\Listeners\ExampleListener2::class,
\App\Listeners\ExampleListener3::class,
]
];
You can choose either of these methods to configure event listeners based on your project requirements.
In this complete example, we'll create a custom event and listener, configure the event dispatcher, and demonstrate dependency injection in a controller. We'll use the Essential Framework's default event dispatcher, devcoder-xyz/php-event-dispatcher
.
Let's create a custom event class named ExampleEvent
. This event will carry an object and will be dispatched from the controller.
// src/Event/ExampleEvent.php
namespace App\Event;
use DevCoder\Listener\Event;
final class ExampleEvent extends Event
{
private object $object;
public function __construct(object $object)
{
$this->object = $object;
}
public function getObject(): object
{
return $this->object;
}
}
Next, create an event listener class named ExampleListener
. This listener will respond to the ExampleEvent
by logging a message.
// src/Listeners/ExampleListener.php
namespace App\Listeners;
use App\Event\ExampleEvent;
use Psr\Log\LoggerInterface;
final class ExampleListener
{
private LoggerInterface $logger;
public function __construct(LoggerInterface $logger)
{
$this->logger = $logger;
}
public function __invoke(ExampleEvent $event): void
{
$object = $event->getObject();
$this->logger->info("ExampleListener has received an object with name: {$object->name}");
}
}
Configure the event listeners in the listeners.php
configuration file. We will map the ExampleEvent
to the ExampleListener
.
// config/listeners.php
return [
\App\Event\ExampleEvent::class => \App\Listeners\ExampleListener::class,
];
Now, let's inject the event dispatcher and demonstrate dependency injection in a controller.
// src/Controllers/MainController.php
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\EventDispatcher\EventDispatcherInterface;
use App\Event\ExampleEvent;
class MainController
{
private EventDispatcherInterface $eventDispatcher;
public function __construct(EventDispatcherInterface $eventDispatcher)
{
$this->eventDispatcher = $eventDispatcher;
}
public function __invoke(ServerRequestInterface $request): ResponseInterface
{
// Your application logic goes here
// For demonstration purposes, let's dispatch an example event
$user = new stdClass();
$user->name = 'John Doe';
// Create an instance of your custom event
$exampleEvent = new ExampleEvent($user);
// Dispatch the event using the event dispatcher
$this->eventDispatcher->dispatch($exampleEvent);
// You can continue your controller logic here
return response('<h1>Welcome to the Essential Framework!</h1>');
}
}
In this example, we've created a custom event (ExampleEvent
) and an event listener (ExampleListener
). We've configured the event listeners in the listeners.php
configuration file. In the MainController
, we've injected the EventDispatcherInterface
and used it to dispatch the ExampleEvent
. When the controller is invoked, the event listener logs a message based on the event.