Events
Apiato events are just Laravel Events, and they function in the exact same way as Laravel events. However, they come with additional rules and conventions specific to Apiato.
To generate new events and listeners you may use the following interactive commands:
php artisan apiato:generate:event
php artisan apiato:generate:listener
Rulesβ
- All
- Events MUST extend the
App\Ship\Parents\Events\Event
class.- The parent extension SHOULD be aliased as
ParentEvent
.
- The parent extension SHOULD be aliased as
- Listeners MUST extend the
App\Ship\Parents\Listeners\Listener
class.- The parent extension SHOULD be aliased as
ParentListener
.
- The parent extension SHOULD be aliased as
- Events MUST extend the
- All container-specific
- Events MUST be placed in the
app/Containers/{Section}/{Container}/Events
directory. - Listeners MUST be placed in the
app/Containers/{Section}/{Container}/Listeners
directory.
- Events MUST be placed in the
- All general
- Events MUST be placed in the
app/Ship/Events
directory. - Listeners MUST be placed in the
app/Ship/Listeners
directory.
- Events MUST be placed in the
- Listeners CAN listen to all cross-container & cross-section events.
- Events & Listeners MUST be registered in the location where you intend to handle that event.
- If you intend to handle an event in:
- A container, the Listener MUST be registered in
App\Containers\{Section}\{Container}\Providers\EventServiceProvider
class. - The Ship, the Listener MUST be registered in
App\Ship\Providers\EventServiceProvider
class.
- A container, the Listener MUST be registered in
- If you intend to handle an event in:
Folder Structureβ
The highlighted sections showcase event & listener registration points:
app
βββ Containers
β βββ Section
β βββ Container
β βββ Events
β β βββ DemoEvent.php
β β βββ ...
β βββ Listeners
β β βββ DemoListener.php
β β βββ ...
β βββ Providers
β βββ EventServiceProvider.php
β βββ ...
βββ Ship
βββ Events
β βββ ShipDemoEvent.php
β βββ ...
β ββ Listeners
β βββ ShipDemoListener.php
β βββ ...
βββ Providers
βββ EventServiceProvider.php
βββ ...
Code Exampleβ
Events and Listeners are defined exactly as you would define them in Laravel.
Registering Events & Listenersβ
The registration of events and listeners depends on where you intend to respond to events. Listeners can be registered in both container and Ship.
In The Containerβ
Registering events and listeners in the container can be done
by adding them to the listen
array in the App\Containers\{Section}\{Container}\Providers\EventServiceProvider
class.
use ...
use App\Ship\Parents\Providers\EventServiceProvider as ParentEventServiceProvider;
class EventServiceProvider extends ParentEventServiceProvider
{
protected $listen = [
OrderShipped::class => [
SendShipmentNotification::class,
],
];
}
To generate an event service provider
you may use the apiato:generate:provider
interactive command:
php artisan apiato:generate:provider
Remember to also register the EventServiceProvider
in the container's MainServiceProvider
:
use ...
use App\Ship\Parents\Providers\MainServiceProvider as ParentMainServiceProvider;
class MainServiceProvider extends ParentMainServiceProvider
{
protected array $serviceProviders = [
// ... Other service providers
EventServiceProvider::class,
];
}
In The Shipβ
Registering events and listeners in the Ship can be done
by adding them to the listen
array in the App\Ship\Providers\EventServiceProvider
class.
Events & Listeners Registration Flowβ
If you are manually registering events and listeners and wish to understand the registration process, here is a breakdown of the registration flow.
Consider the following folder structure:
app
βββ Containers
β βββ Section
β βββ Container
β βββ Events
β β βββ DemoEvent.php βββββΊββ
β β βββ ... β
β βββ Listeners β
β β βββ DemoListener.php ββΊββ€
β β βββ ... β
β βββ Providers βΌ
β βββ EventServiceProvider.php ββββββββββΊββββββββββ
β βββ MainServiceProvider.php ββββregisteredβinββββ
β βββ ...
βββ Ship
βββ Events
β βββ ShipDemoEvent.php βββΊββ
β βββ ... β
βββ Listeners β
β βββ ShipDemoListener.php βΊβ€
β βββ ... β
βββ Providers βΌ
βββ EventServiceProvider.php ββββββββββΊββββββββββ
βββ ShipProvider.php ββββregisteredβinββββ
βββ ...
The following diagram illustrates the registration flow of events and listeners in the above folder structure: