Events, hooks & filters

Register listeners

Pass listeners to ConveyorServer through eventListeners(), keyed by Constants::EVENT_* names:

<?php

use Conveyor\Constants;
use Conveyor\ConveyorServer;
use Conveyor\Events\MessageReceivedEvent;

require __DIR__ . '/vendor/autoload.php';

(new ConveyorServer())
    ->eventListeners([
        Constants::EVENT_MESSAGE_RECEIVED => function (MessageReceivedEvent $event) {
            var_dump($event->data);
        },
    ])
    ->port(8989)
    ->start();

Lifecycle events

public function __construct(public Server $server)

public function __construct(public Server $server)

public function __construct(public Server $server, public int $fd)

Message events

EVENT_BEFORE_MESSAGE_HANDLED and EVENT_AFTER_MESSAGE_HANDLED wrap the native Conveyor action pipeline. For Pusher frame observation, use ACTION_PUSHER_MESSAGE_RECEIVED instead.

public function __construct(
    public Server $server,
    public string $data,
    public int $taskId,
    public int $reactorId,
)

public function __construct(
    public Server $server,
    public string $data,
    public int $fd,
)

public function __construct(
    public Server $server,
    public string $data,
    public int $fd,
)

HTTP and task events

public function __construct(
    public Request $request,
    public Response $response,
)

public function __construct(
    public Server $server,
    public string $data,
    public int $taskId,
)

Hooks and filters

Conveyor uses Hook\Filter and Hook\Action from its Composer dependency lotharthesavior/hook. A filter transforms a value and must return its replacement. An action runs a callback for observation or side effects; its return value does not replace the message or act as an authorization decision.

These hooks are distinct from the eventListeners() lifecycle listeners above and from custom native protocol handlers registered with Constants::ACTIONS. Hook actions are available in Pusher mode; native protocol action handlers are not used by the Pusher router.

Availability and callback arguments

The names below are members of Conveyor\Constants. Availability is checked against Conveyor 2.6.1, source commit ce077686; a declared constant alone does not establish that a protocol invokes it.

FILTER_PRESENCE_MESSAGE_DISCONNECT is declared in this version but has no invocation in the inspected source. Do not rely on it firing. The native presence implementation uses FILTER_PRESENCE_MESSAGE_CONNECT for its presence payload.

Register hooks before starting the server

Load Composer, then register callbacks once in your PHP entrypoint before calling start(). Callbacks run in the server processes; captured PHP variables are not shared storage across workers. The optional third registration argument is a numeric priority: lower values run first, and equal priorities retain registration order.

This shared outbound filter observes frame size and returns the original frame. Replace the returned string only when your transformation preserves the selected protocol’s frame format:

<?php
require __DIR__ . '/vendor/autoload.php';

use Conveyor\Constants;
use Conveyor\ConveyorServer;
use Hook\Filter;
use OpenSwoole\WebSocket\Server;

Filter::addFilter(
    Constants::FILTER_PUSH_MESSAGE,
    function (string $data, int $fd, Server $server): string {
        error_log('Outgoing frame bytes: ' . strlen($data));
        return $data;
    },
);

// Native mode; the same filter also runs with a configured Pusher server.
(new ConveyorServer())->port(8989)->start();

For Pusher mode, add an observer to the PHP entrypoint used by your configured Pusher server, before start(). This example records only the event name and connection descriptor:

use Hook\Action;

Action::addAction(
    Constants::ACTION_PUSHER_MESSAGE_RECEIVED,
    function (int $fd, string $raw, array $frame, Server $server): void {
        error_log('Pusher event ' . $frame['event'] . ' on fd ' . $fd);
    },
);

The action callback observes the parsed frame; changing its local array or returning a value does not rewrite the event processed by the router. Use FILTER_PUSH_MESSAGE for outgoing transformations. Preserve Pusher fields such as event, channel and the protocol’s encoded data; native message envelopes are different.

Keep callbacks short and avoid logging raw frames, credentials or private payloads. Filters may run once per recipient, and actions observe processing rather than durable delivery. A custom native action handler does not add a Pusher event handler.

The stock Docker launcher does not expose hook registration through environment variables. To register PHP callbacks with Docker, supply a custom PHP entrypoint as described in the Docker setup and upstream Docker guide.

Source reference

Inspect the Pusher router, Pusher REST controller, native broadcast implementation, native worker and hook constants for the invocation points and argument order.