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.
  • Listeners MUST extend the App\Ship\Parents\Listeners\Listener class.
    • The parent extension SHOULD be aliased as ParentListener.
• 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.
• All general
  • Events MUST be placed in the app/Ship/Events directory.
  • Listeners MUST be placed in the app/Ship/Listeners directory.
• 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.

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: