Skip to main content
Version: 9.x

Events

Definition#

Events:

  • Events provide a simple observer implementation, allowing you to subscribe and listen for various events that occur in your application.
  • Events are classes that can be fired from anywhere in your application.
  • An event class will usually be bound to one or many Events Listeners Classes or has those Listeners registered to listen to it.
  • "fire" is the term that is usually used to call an Event.

More details here.

Principles#

  • Events can be fired from Actions and or Tasks. It's preferable to choose one place only. (Tasks are recommended).
  • Events SHOULD be created inside the Containers. However, general Events CAN be created in the Port layer.

Rules#

  • Event classes CAN be placed inside the Containers in Events folders or on the Ship for the general Events.
  • All Events MUST extend from App\Ship\Parents\Events\Event.

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.

  • The ShouldHandleNow Interface will make the event execute the handle method as soon as the event gets dispatched.

  • The ShouldHandle Interface will create an eventjob and execute the handle method async (through laravel jobs).

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.

Last updated on by Moslem Deris