surrealdb/surrealdb.php

The official SurrealDB SDK for PHP.

Maintainers

Package info

github.com/surrealdb/surrealdb.php

pkg:composer/surrealdb/surrealdb.php

Transparency log

Statistics

Installs: 1 626

Dependents: 2

Suggesters: 0

Stars: 69

Open Issues: 1

Security

Advisories: 0

Aikido package health analysis

2.0.0-alpha.2 2026-07-22 11:20 UTC

Requires

Requires (Dev)

Suggests

  • amphp/http-client: Non-blocking HTTP transport for the Amp/Revolt runtime
  • amphp/http-client-psr7: Non-blocking PSR-18 client for OTLP export on the Amp/Revolt runtime (Runtime::amp with ObservabilityOptions)
  • amphp/websocket-client: Async WebSocket transport for the Amp/Revolt runtime
  • guzzlehttp/guzzle: PSR-18 HTTP client and PSR-17 factories used by the default HTTP engine
  • open-telemetry/api: Emit OpenTelemetry traces and metrics via the bundled SurrealDB\SDK\Telemetry\OpenTelemetry adapter
  • open-telemetry/exporter-otlp: OTLP exporter used by the runtime-aware observability presets to ship traces and metrics
  • open-telemetry/sdk: Configure OpenTelemetry providers via the runtime-aware observability presets (Runtime::sync/swoole/amp with ObservabilityOptions)
  • openswoole/core: Run the SDK on OpenSwoole coroutines (native async WebSocket client and non-blocking HTTP via runtime hooks)
  • php-http/discovery: Automatic discovery of the installed PSR-18 client and PSR-17 factories
  • revolt/event-loop: Fiber-based event loop powering the Amp runtime (e.g. FrankenPHP worker mode)

Apache-2.0 2cbc1321bbd59d7bdb7b55568cdc4d3e44f5fcac

databasewebsocketclientsdksurrealdb

Published on Packagist.org on 2026-07-22 11:22 UTC

This package is auto-updated.

Last update: 2026-07-22 11:23:28 UTC

README


 

The official SurrealDB SDK for PHP.


     

     

surrealdb.php

The official SurrealDB SDK for PHP.

Documentation

View the SDK documentation here.

How to install

You install the SurrealDB SDK via Composer. If you don't have Composer installed, you can download it here.

composer require surrealdb/surrealdb.php

Getting started

To get started, you need to create a new instance of the SurrealDB HTTP or WebSocket Class.

// Make a new instance of the SurrealDB class. Use the ws or wss protocol for having WebSocket functionality.
$db = new \Surreal\Surreal();

$db->connect("http://localhost:8000", [
    "namespace" => "test",
    "database" => "test"
]);

Basic Querying

In the PHP SDK, We have a simple API that allows you to interact with SurrealDB. The following example shows how to interact with the database.

The example below requires SurrealDB to be installed and running on port 8000.

// Connect set the specified namespace and database.
$db = new \Surreal\Surreal();

$db->connect("http://localhost:8000", [
    "namespace" => "test",
    "database" => "test"
]);

// We want to authenticate as a root user.
$token = $db->signin([
    "user" => "root",
    "pass" => "root"
]);

// Create a new person in the database with a custom id.
$person = $db->create("person", [
    "title" => "Founder & CEO",
    "name" => [
        "first" => "Tobie",
        "last" => "Morgan Hitchcock" 
    ],
    "marketing" => true
]); 

// Get the person with the name "John Doe".
$record = \Surreal\Cbor\Types\Record\RecordId::create("person", "john");
$person = $db->select($record);

// Update a person record with a specific id
$record = \Surreal\Cbor\Types\Record\RecordId::create("person", "john");
$person = $db->merge($record, ["age" => 31]);

// Select all people records.
$people = $db->select("person");  

// Perform a custom advanced query.
$groups = $db->query('SELECT marketing, count() FROM $tb GROUP BY marketing', [
    "tb" => \Surreal\Cbor\Types\Table::create("person")
]);

// Close the connection between the application and the database.
$db->close();

Observability

The SDK emits OpenTelemetry traces and metrics for every RPC. Enable it per runtime through the Runtime presets, which pick the export strategy that fits each environment:

  • PHP-FPM / CLI (Runtime::sync): spans are buffered in a batch processor and flushed once the request finishes (after fastcgi_finish_request() under FPM), so export never adds to user-visible latency.
  • OpenSwoole / FrankenPHP (Amp) (Runtime::swoole / Runtime::amp): each span is exported directly with no batching, over a non-blocking transport (Swoole runtime hooks, or the Amp PSR-18 client).
use SurrealDB\SDK\Runtime\Runtime;
use SurrealDB\SDK\Surreal;
use SurrealDB\SDK\Telemetry\OpenTelemetry\ObservabilityOptions;

$observability = new ObservabilityOptions(
    endpoint: "http://localhost:4318", // OTLP collector
    serviceName: "my-app",
);

// PHP-FPM / CLI: batch in memory, flush after the request.
$db = new Surreal(Runtime::sync(observability: $observability));

// OpenSwoole / FrankenPHP: direct, non-blocking export.
$db = new Surreal(Runtime::swoole(observability: $observability));
$db = new Surreal(Runtime::amp(observability: $observability));

Requires open-telemetry/sdk and open-telemetry/exporter-otlp (plus amphp/http-client-psr7 for the Amp runtime).

Flushing after the response in a framework

When the framework owns the response lifecycle (e.g. Laravel), build the providers yourself and flush in a terminable hook rather than relying on the shutdown handler:

use SurrealDB\SDK\Connection\DriverOptions;
use SurrealDB\SDK\Surreal;
use SurrealDB\SDK\Telemetry\OpenTelemetry\ObservabilityOptions;
use SurrealDB\SDK\Telemetry\OpenTelemetry\OtelObservability;

$telemetry = OtelObservability::batched(new ObservabilityOptions(serviceName: "my-app"));

$db = new Surreal(new DriverOptions(
    tracer: $telemetry->tracer(),
    meter: $telemetry->meter(),
));

// Laravel: flush after the response has been sent to the client.
app()->terminating(static fn () => $telemetry->forceFlush());

Contributing

Requirements

  • PHP 8.4 or higher
  • Composer
  • SurrealDB 2.6.2 or higher

Run static analysis

composer analyse

Run tests

composer test

Directory Structure

  • src - The source code of the library
  • tests - The unit tests of the library