Events

Version 2 of the PHP SDK exposes two ways to observe what it is doing. The high-level subscribe() method covers connection lifecycle changes with a simple callback. The lower-level PSR-14 event dispatcher emits a richer stream that includes per-request events, and integrates with framework dispatchers.

Lifecycle events with subscribe()

Use subscribe() for quick hooks into the connection lifecycle. Pass an event name and a listener; the method returns a closure that removes the listener when called.

$unsubscribe = $db->subscribe('connected', function (string $version): void {
    echo "Connected to SurrealDB {$version}";
});

// later
$unsubscribe();

The available event names are connecting, connected, reconnecting, disconnected, error, auth, and using. This is the simplest option when you only need to react to the connection coming up, dropping, or re-authenticating. See Connecting to SurrealDB and Authentication for lifecycle examples.

PSR-14 events

For full observation, including every RPC request and response, the SDK dispatches typed event objects through a PSR-14 event dispatcher. Unlike subscribe(), this stream reaches RPC-level events and lets you reuse a framework's dispatcher.

By default the SDK creates its own dispatcher. To receive events, either register listeners on a dispatcher you control and pass it through DriverOptions, or pass your framework's PSR-14 dispatcher.

use SurrealDB\SDK\Surreal;
use SurrealDB\SDK\Connection\DriverOptions;
use SurrealDB\SDK\Events\EventDispatcher;
use SurrealDB\SDK\Events\ListenerProvider;
use SurrealDB\SDK\Events\RpcResponseReceived;

$provider = new ListenerProvider();
$provider->on(RpcResponseReceived::class, function (RpcResponseReceived $event): void {
    error_log($event->request->method);
});

$db = new Surreal(new DriverOptions(
    events: new EventDispatcher($provider),
));

The bundled ListenerProvider matches a listener against the event class and any of its parents or interfaces, so you can listen to a single event type or a shared base.

Using a framework dispatcher

Because the SDK depends only on the PSR-14 EventDispatcherInterface, you can pass the dispatcher from Laravel, Symfony, or any PSR-14 bridge. The SDK then dispatches its events into your application's existing listener setup.

$db = new Surreal(new DriverOptions(
    events: $container->get(\Psr\EventDispatcher\EventDispatcherInterface::class),
));

Event catalogue

All events live in the SurrealDB\SDK\Events namespace and are readonly value objects.

use SurrealDB\SDK\Events\RpcRequestSent;
use SurrealDB\SDK\Events\AuthChanged;

$provider->on(RpcRequestSent::class, function (RpcRequestSent $event): void {
    // $event->request->method, $event->request->params
});

$provider->on(AuthChanged::class, function (AuthChanged $event): void {
    // $event->tokens is null when the session is signed out
});

Choosing between them

• Use subscribe() for connection lifecycle hooks with the least setup.

• Use the PSR-14 dispatcher when you need per-request events, want to fan events into a framework's listeners, or are building observability tooling.

Learn more

• Surreal API reference for the subscribe() signature

• Observability for tracing and metrics

• Connecting to SurrealDB for the lifecycle these events track