Real-Time Signalling

Real-Time Signalling

Warlock provides a powerful real-time signalling system that enables instantaneous communication between different components of your application. This includes:

• Server-to-Server: Services and processes running on the backend.
• Server-to-Client: Backend processes pushing updates to frontend browsers.
• Client-to-Server: Browsers triggering events on the backend.
• Client-to-Client: Browsers communicating directly with each other (via the server).

Architecture

Real-time signalling is managed centrally by the Warlock Server. It maintains persistent connections with clients and routes messages between them. The server is responsible for:

• Connection Management: Handling WebSocket and UNIX socket connections.
• Routing: Delivering messages to the correct recipients (e.g., specific clients, services, or namespaces).
• Broadcasting: Sending messages to all connected clients or subscribers.

Triggering Events

Events are the core mechanism for signalling. You can trigger an event from PHP code using the Hazaar\Warlock\Client.

use Hazaar\Warlock\Client;

$client = new Client();
if ($client->connect()) {
    // Trigger a simple event
    $client->trigger('testEvent', 'Hello, World!');

    // Trigger an event with complex data
    $client->trigger('orderUpdated', [
        'orderId' => 1234,
        'status' => 'shipped'
    ]);
    
    $client->disconnect();
}

Receiving Events (Server-Side)

Services

Long-running Services can subscribe to events to maintain state or perform actions without the overhead of spawning new processes. This is done using the subscribe method, typically within the service's init() or run() lifecycle methods.

namespace App\Service;

use Hazaar\Warlock\Service;
use Hazaar\Warlock\Enum\LogLevel;

class OrderService extends Service
{
    public function init(): bool
    {
        // Subscribe to the 'orderUpdated' event
        $this->subscribe('orderUpdated', function($data) {
            $this->log("Order updated: " . json_encode($data), LogLevel::INFO);
            
            // Perform logic like updating a local cache or notifying other systems
        });
        
        return true;
    }
}

Event Handlers

For ad-hoc execution where a persistent service is not required, use Event Handlers.

Receiving Events (Client-Side)

The JavaScript client allows web browsers to subscribe to events, enabling real-time UI updates (e.g., chat messages, notifications, live dashes).

Setup

First, ensure the Warlock JavaScript library is included in your page. Then, initialize the client.

import { createWarlock } from '/libs/js/warlock.js';

// Connect to the Warlock server
const warlock = createWarlock('wss://your-warlock-server.com');

warlock.connect(function(status) {
    console.log('Connected to Warlock!', status);
});

Subscribing

Use the subscribe method to listen for specific events.

// Subscribe to 'orderUpdated'
warlock.subscribe('orderUpdated', function(data) {
    console.log('Received order update:', data);
    
    // Update the UI
    document.getElementById('status').innerText = data.status;
});

Triggering from Client

Clients can also trigger events that will be received by the server (Services/Event Handlers) and other connected clients subscribed to that event.

// Trigger an event from the browser
warlock.trigger('clientAction', { 
    action: 'click', 
    timestamp: Date.now() 
});