GitHub Repository

apiato

Definition

Events:

More details here.

Principles

Rules

Folder Structure

 - App
    - Containers
        - {container-name}
            - Events
                - SomethingHappenedEvent.php
                - ...
            - Listeners
                - ListenToMusicListener.php
                - ...

    - Ship
        - Events
            - GlobalStateChanged.php
            - SomethingBiiigHappenedEvent.php
            - ...

Enabling Events

Before you can use events you need to add the EventServiceProvider to the MainServiceProvider of the Ship (if this has not been registered so far). See example below.

<?php

namespace App\Containers\Car\Providers;

class MainServiceProvider extends MainProvider
{

    /**
     * Container Service Providers.
     *
     * @var array
     */
    public $serviceProviders = [
        EventServiceProvider::class,
    ];

    // ...
}

Usage

In Laravel you can create and register events in multiple way. Below is an example of an Event that handles itself.

Event Class Example:

<?php

namespace App\Containers\User\Events;

use App\Containers\User\Models\User;
use App\Ship\Parents\Events\Event;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Log;

class UserRegisteredEvent extends Event implements ShouldQueue
{
    protected $user;

    public function __construct(User $user)
    {
        $this->user = $user;
    }

    public function handle()
    {
        Log::info('New User registration. ID = ' . $this->user->getHashedKey() . ' | Email = ' . $this->user->email . '.');

        // ...
    }

    public function broadcastOn()
    {
        return new PrivateChannel('channel-name');
    }
}

Note: You will get more benefits creating Events Listeners for each Event.

To do this you will need to create a custom EventServiceProvider in your container extending App\Ship\Parents\Providers\EventsProvider.

Your custom EventServiceProvider needs to be registered in the containers MainServiceProvider as well.

<?php

namespace App\Containers\Car\Providers;

use App\Ship\Parents\Providers\MainProvider;

/**
 * Class MainServiceProvider.
 *
 * The Main Service Provider of this container, it will be automatically registered in the framework.
 */
class MainServiceProvider extends MainProvider
{

    /**
     * Container Service Providers.
     *
     * @var array
     */
    public $serviceProviders = [
        EventServiceProvider::class,
    ];

Dispatch Events

You can dispatch an Event from anywhere you want (ideally from Actions and Tasks).

Example: Dispatching the Event class from the example above

<?php

// using helper function
event(New UserEmailChangedEvent($user));

// manually
\App::make(\Illuminate\Contracts\Bus\Dispatcher\Dispatcher::class)->dispatch(New UserEmailChangedEvent($user));

Queueing an Event

Events can implement Illuminate\Contracts\Queue\ShouldQueue to be queued.

Handling an Event

You can handle jobs on dispatching an event.

To do so you need to implement one of the following interfaces:

Apiato\Core\Abstracts\Events\Interfaces\ShouldHandleNow

Apiato\Core\Abstracts\Events\Interfaces\ShouldHandle

This will force you to implement the handle method and will make apiato execute the method upon dispatching the event.

namespace App\Containers\Example\Events;


use Apiato\Core\Abstracts\Events\Interfaces\ShouldHandle;
use App\Ship\Parents\Events\Event;

class ExampleEvent extends Event implements ShouldHandle
{
    /**
     * If ShouldHandle interface is implemented this variable
     * sets the time (in seconds or timestamp) to wait before a job is executed
     *
     * @var \DateTimeInterface|\DateInterval|int|null $jobDelay
     */
    public $jobDelay = 60;

    /**
     * If ShouldHandle interface is implemented this variable
     * sets the name of the queue to push the job on
     *
     * @var string $jobQueue
     */
    public $jobQueue = "example_queue";

    public function handle()
    {
        // Do some handling here
    }
    
}

Broadcasting

Note: to define Broadcasting route go to app/Ship/Boardcasts/Routes.php.