This package allows you to define all of your events in a simple configuration file.
Events in Laravel are a fantastic tool to use. However, once you start leaning into events heavily, managing everything through the service provider can be a bit cumbersome. While event discovery exists (since Laravel 5.8), this doesn't always solve the entire problem. This package will allow you to define listeners, subscribers, and observers within a configuration file. Additionally, the implementation allows you to be a bit more lackadaisical with registration, with no performance cost after caching events.
First, start by installing this package.
composer require reedware/laravel-events
Next, you'll need to get your hands on the events.php configuration file. You can either copy it directly, or publish it.
php artisan vendor:publish
Finally, you'll need to modify your service provider. You can either extend the example provider in the package, or you can utilize the trait.
<?php
namespace App\Providers;
use Reedware\LaravelEvents\EventServiceProvider as ServiceProvider;
class EventServiceProvider extends ServiceProvider
{
}<?php
namespace App\Providers;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
use Reedware\LaravelEvents\ConfiguredEvents;
class EventServiceProvider extends ServiceProvider
{
use ConfiguredEvents;
}If you've overridden the default listens() method, be sure to yield the configured events:
/**
* Returns the events and handlers.
*
* @return array
*/
public function listens()
{
$myEventOverrides = [/* ... */];
return array_merge_recursive(
$myEventOverrides,
$this->configuredEvents()
);
}After that, you're good to start configuring your events!
This package offers four types of event registration:
- Event / Listener Mapping
- Subscriber / Event Mapping
- Observer / Model Mapping
- Model / Observer Mapping
As you dive in, you'll discover that there's more than one way to register an event binding. This package offers various alternatives so that you can do whatever makes the most since for you and your application.
This is the traditional "listens" array that is typically a property within your EventServerProvider. You can list each event, and the listeners that listen to them.
Example:
'listen' => [
// When a user has registered...
Illuminate\Auth\Events\Registered::class => [
// Send an email verification notification
Illuminate\Auth\Listeners\SendEmailVerificationNotification::class
],
],If your listener doesn't use the traditional handle method, you can call out the method directly like so:
'listen' => [
// When a user has registered...
Illuminate\Auth\Events\Registered::class => [
[App\Listeners\MyCustomListener::class, 'handleRegistration'],
// or
'App\Listeners\MyCustomListener@handleRegistration'
],
],If your alternative method starts with the word handle (e.x. handleRegistration), and accepts the type-hinted event, you don't have do specify the custom method explicitly:
Listener:
<?php
namespace App\Listeners;
use Illuminate\Auth\Events\Registered;
class MyCustomListener
{
/**
* Handles the specified registration event.
*
* @param \Illuminate\Auth\Events\Registered $event
*
* @return void
*/
public function handleRegistration(Registered $event)
{
//
}
}Configuration:
'listen' => [
// When a user has registered...
Illuminate\Auth\Events\Registered::class => [
// Handle the event
App\Listeners\MyCustomListener::class,
],
],Since you can utilize a non handle method through implicit or explicit binding, you could technically register your subscribers within the Event / Listener mapping. This can make sense if you want to list your subscribers under each respective event, rather than listing all events that are subscribed to.
Example:
'listen' => [
// When a user has registered...
Illuminate\Auth\Events\Registered::class => [
// Send a slack notification
App\Listeners\SendSlackNotification::class,
],
// When a user has logged out...
Illuminate\Auth\Events\Logout::class => [
// Send a slack notification
App\Listeners\SendSlackNotification::class,
],
],When working with subscribers, it often makes sense to list the subscribed events together. When listing subscribers in the configuration file, they do not need a subscribe method.
Configuration:
'subscribe' => [
// Log a security event...
App\Listeners\LogSecurityEvent::class => [
// When a user provided incorrect credentials
Illuminate\Auth\Events\Failed::class,
// When a user has been locked out
Illuminate\Auth\Events\Lockout::class,
// When a user has reset their password
Illuminate\Auth\Events\PasswordReset::class,
],
],Subscriber:
<?php
namespace App\Listeners;
use Illuminate\Auth\Events\Failed;
use Illuminate\Auth\Events\Lockout;
use Illuminate\Auth\Events\PasswordReset;
class LogSecurityEvent
{
/**
* Handles failed login attempts.
*/
public function handleFailed(Failed $event)
{
//
}
/**
* Handles too many login attempts.
*/
public function handleLockout(Lockout $event)
{
//
}
/**
* Handles successful password resets.
*/
public function handlePasswordReset(PasswordReset $event)
{
//
}
}Remember that implicit bindings requires the method to start with the word handle, even when type-hinted.
Pro-Tip: If you plan to always use implicit bindings for subscribers, consider using Event Discovery!
Similar to the event / listener mapping, you may also use expicit binding:
'subscribe' => [
// Log a security event...
App\Listeners\LogSecurityEvent::class => [
// When a user provided incorrect credentials
[Illuminate\Auth\Events\Failed::class, 'failed'],
// When a user has been locked out
[Illuminate\Auth\Events\Lockout::class, 'lockout'],
// When a user has reset their password
'Illuminate\Auth\Events\PasswordReset@reset',
],
],When fully utilized, observers often observe more than one model. Listing the models under the observers make more sense in this case. Here's how you can configure observers:
'observe' => [
// Track the creator for each of the following models...
App\Observers\UserObserver::class => [
App\Models\Country::class,
App\Models\Post::class,
App\Models\State::class,
App\Models\User::class,
]
],This package fully supports custom observables, provided that they are registered either as a property or within the construction of the model.
You may prefer to instead list out models, and describe the observers beneath them. Both options are provided so that you can do what makes the most sense for you and your application. Here's how listing the model first would work:
'models' => [
// Observe the user
App\Models\User::class => [
App\Observers\UserObserver::class,
]
],This package fully supports Event Caching. In fact, given how observers are registered under the hood, you will likely see a significant performance boost if you're using a lot of observers within your application.
To cache events, run the event:cache artisan command. Should you need to clear the event cache, you can run the event:clear artisan command.
This package fully supports Event Discovery, and it does not conflict with the configuration file. Both configured events and discovered events are merged in the registration process.
Additionally, any section of the event configuration can be omitted entirely. If you decide to use event discovery for all of your events, and wish to only configure your observers, you can remove the "listen" and "subscribe" arrays without issue.