Event Handlers

Warlock provides a robust event system allowing different parts of your application to communicate asynchronously. Events can be triggered by client requests, services, or other internal processes.

Unlike services, which must be running constantly to listen for events, Event handlers allow you to execute code in response to an event without a persistent process. When an event is triggered, Warlock spawns a short-lived Container process to handle the event and then terminates it once the task is complete. This approach is ideal for infrequent tasks or when you want to minimize resource usage.

Tips

If you need high-performance, low-latency event handling for frequent events, consider using a Service subscription instead, as it avoids the overhead of spawning a new process for each event. Services also continue to run between events, making them useful for maintaining state or managing long-running resources.

Creating an Event Handler

To implement an event handler, you create a class that contains the logic you want to execute. It is recommended to extend Hazaar\Warlock\Agent\Container, which provides helper methods like logging.

namespace App\Model;

use Hazaar\Warlock\Agent\Container;
use Hazaar\Warlock\Enum\LogLevel;

class MyEventHandler extends Container
{
    public function handleTestEvent(\stdClass $packet): void
    {
        // $packet->data contains the payload sent with the trigger
        $this->log('Received event data: ' . $packet->data, LogLevel::INFO);
        
        // You can perform any action here, like updating a database, sending an email, etc.
    }
}

Event Payload Structure

Unlike standard code endpoints which can accept multiple arguments matching the parameters sent by the caller, Event Handlers receive a single argument. This argument is a stdClass object representing the event packet.

The packet object typically contains the following properties:

• id: The name of the event (e.g., "testEvent").
• trigger: A unique identifier for this specific trigger instance (e.g., "699e803f8f594").
• time: The timestamp when the event was triggered (e.g., 1771995199.587206).
• data: The custom data payload sent with the trigger (e.g., "Hello, World!" or an array/object).

Configuration

Register your event handler in your Warlock configuration file (e.g., warlock.json or your application's config.json). Map the event name to your class and method.

PHP (Recommended)

<?php
return [
    'events' => [
        'testEvent' => 'App\Model\MyEventHandler::handleTestEvent'
    ]
];

JSON

{
    "events": {
        "testEvent": "App\\Model\\MyEventHandler::handleTestEvent"
    }
}

INI (Legacy)

[events]
testEvent = "App\Model\MyEventHandler::handleTestEvent"

In this example:

• testEvent: The name of the event to listen for.
• App\Model\MyEventHandler::handleTestEvent: The class and method to execute.

Triggering Events

You can trigger events from anywhere in your application using the Hazaar\Warlock\Client.

use Hazaar\Warlock\Client;

$client = new Client();
$client->connect();

// Trigger 'testEvent' with a payload string
$client->trigger('testEvent', 'Hello, World!');

// You can also send arrays or objects
$client->trigger('userSignedUp', ['userId' => 12345]);

$client->disconnect();

Service Events

Persistent services can also subscribe to events, which is particularly useful for maintaining state or managing long-running resources. For detailed information on how services handle events, refer to the Real-Time Signalling documentation.