Skip to main content

Events

The Events system provides a simple observer implementation, allowing you to subscribe and listen for various events that occur within your application. This loose coupling allows you to separate your application logic into distinct, reusable components.

Setup​

The Event system is built into the core framework and does not require extensive configuration. However, you need to ensure your listeners are registered.

Registration​

Listeners are registered in the configs/listeners.cache.php file (or a similar configuration path, depending on your app structure). This file returns an array mapping Event classes to an array of Listener classes.

Structure:

return [
    \Ecommerce\App\Events\OrderCreated::class => [
        \Ecommerce\App\Listeners\SendOrderConfirmationEmail::class,
        \Ecommerce\App\Listeners\UpdateInventory::class,
    ],
];

Defining Events​

Events are simple PHP data classes (DTOs) that hold the information related to the event.

Event Class​

Define the structure of an Event class.

Description:

An Event class typically contains public properties that Listeners can access. It acts as a container for data passing from the dispatcher to the listeners.

Examples:

<?php

namespace Ecommerce\App\Events;

use Ecommerce\App\Models\Order;

class OrderCreated
{
    /**
     * The order instance.
     *
     * @var Order
     */
    public $order;

    /**
     * Create a new event instance.
     *
     * @param Order $order
     * @return void
     */
    public function __construct(Order $order)
    {
        $this->order = $order;
    }
}

Defining Listeners​

Listeners are classes that handle the logic when a specific event is fired.

Listener Class​

Define the structure of a Listener class.

Description:

A Listener class must extend the Ecommerce\Core\Listener base class and implement a handle method. The handle method receives the Event instance as its argument.

Method Signature:

public function handle(object $event): void

Parameters:

  • $event - The instance of the Event class being handled.

Examples:

<?php

namespace Ecommerce\App\Listeners;

use Ecommerce\Core\Listener;
use Ecommerce\App\Events\OrderCreated;

class SendOrderConfirmationEmail extends Listener
{
    /**
     * Handle the event.
     *
     * @param OrderCreated $event
     * @return void
     */
    public function handle($event)
    {
        $order = $event->order;

        // logic to send email...
        wp_mail(
            $order->customer->email,
            'Order Confirmed #' . $order->id,
            'Thank you for your order...'
        );
    }
}

Listener Priority​

You can define the execution order of listeners.

Description:

Override the priority() method to specify the listener's priority. Higher values indicate higher priority. The default priority is 0.

Method Signature:

public function priority(): int

Examples:

public function priority()
{
    // This listener will run before listeners with lower priority
    return 10;
}

Dispatching Events​

Use the Event facade to dispatch events to their registered listeners.

Dispatch​

Dispatch an event to all registered listeners.

Description:

The dispatch() method accepts an event instance and triggers all listeners associated with that event class.

Method Signature:

public static function dispatch(object $event): void

Parameters:

  • $event - The event instance to dispatch.

Examples:

use Ecommerce\Supports\Facades\Event;
use Ecommerce\App\Events\OrderCreated;
use Ecommerce\App\Models\Order;

$order = Order::find(123);

// Dispatch the event
Event::dispatch(new OrderCreated($order));

Dispatch If​

Dispatch an event only if a condition is met.

Description:

The dispatch_if() method checks a boolean condition (provided as a Closure). If the condition returns true, the event is dispatched.

Method Signature:

public static function dispatch_if(\Closure $boolean, object $event): void

Parameters:

  • $boolean - A Closure that returns a boolean.
  • $event - The event instance.

Examples:

use Ecommerce\Supports\Facades\Event;

Event::dispatch_if(function ($event) {
    return $event->order->total > 1000;
}, new OrderCreated($order));

Dispatch Unless​

Dispatch an event unless a condition is met.

Description:

The dispatch_unless() method checks a boolean condition. If the condition returns false, the event is dispatched.

Method Signature:

public static function dispatch_unless(\Closure $boolean, object $event): void

Parameters:

  • $boolean - A Closure that returns a boolean.
  • $event - The event instance.

Examples:

use Ecommerce\Supports\Facades\Event;

Event::dispatch_unless(function ($event) {
    return $event->order->is_test_order;
}, new OrderCreated($order));