PHPackages                             surrealdb/surrealdb.php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. surrealdb/surrealdb.php

ActiveLibrary[Database & ORM](/categories/database)

surrealdb/surrealdb.php
=======================

The official SurrealDB SDK for PHP.

1.0.1(5mo ago)691.6k↓54.9%14[1 issues](https://github.com/surrealdb/surrealdb.php/issues)2MITPHPPHP >=8.2CI passing

Since May 13Pushed 5mo ago14 watchersCompare

[ Source](https://github.com/surrealdb/surrealdb.php)[ Packagist](https://packagist.org/packages/surrealdb/surrealdb.php)[ Docs](https://github.com/surrealdb/surrealdb.php)[ RSS](/packages/surrealdb-surrealdbphp/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (6)Dependencies (13)Versions (18)Used By (2)

 [![](https://raw.githubusercontent.com/surrealdb/icons/main/surreal.svg)](https://raw.githubusercontent.com/surrealdb/icons/main/surreal.svg) [![](https://raw.githubusercontent.com/surrealdb/icons/main/php.svg)](https://raw.githubusercontent.com/surrealdb/icons/main/php.svg)

### The official SurrealDB SDK for PHP.

[](#the-official-surrealdb-sdk-for-php)

 [![](https://camo.githubusercontent.com/f5856bc80bdc468b8be940fd57eaaabd1c8f98a272a00472102f2fa276677ecd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d626574612d6666303062622e7376673f7374796c653d666c61742d737175617265)](https://github.com/surrealdb/surrealdb.php) [![](https://camo.githubusercontent.com/2bc3bce9c0c19f9061b435744ba7f1b6c17ab027dbf94f3aad720bf25332775a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f63732d766965772d3434636331312e7376673f7374796c653d666c61742d737175617265)](https://surrealdb.com/docs/integration/libraries/php) [![](https://camo.githubusercontent.com/4abf904144a06b9658c87579a10433ea60747fce806e84334d313f04d9eb9076/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7375727265616c64622f7375727265616c64622e7068703f7374796c653d666c61742d737175617265)](https://packagist.org/packages/surrealdb/surrealdb.php) [![](https://camo.githubusercontent.com/609397df38d66ac053e33fc8f7a9f13c7bf6cebba93e18bf3a840ca02d2adbce/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f7375727265616c64622f7375727265616c64622e7068703f7374796c653d666c61742d737175617265)](https://packagist.org/packages/surrealdb/surrealdb.php)

 [![](https://camo.githubusercontent.com/2a5ffe37a41aa065615108550a433289bb94b7eb81218effc1a92fd26f8127e1/68747470733a2f2f696d672e736869656c64732e696f2f646973636f72642f3930323536383132343335303539393233393f6c6162656c3d646973636f7264267374796c653d666c61742d73717561726526636f6c6f723d356136366636)](https://surrealdb.com/discord) [![](https://camo.githubusercontent.com/29cc2219c15bb21734009181b3ab5105b15e60242acc6b43b97dade314c542a7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f747769747465722d666f6c6c6f775f75732d3164396266302e7376673f7374796c653d666c61742d737175617265)](https://twitter.com/surrealdb) [![](https://camo.githubusercontent.com/c0509801cf69ac0dce8fc83bf3c10ef6c80ffac01a09b589e23a7e08d502a1ef/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c696e6b6564696e2d636f6e6e6563745f776974685f75732d3061363663322e7376673f7374796c653d666c61742d737175617265)](https://www.linkedin.com/company/surrealdb/) [![](https://camo.githubusercontent.com/8af816f359bb2a097788d053a4323a0875075704bd1e43768707f155ffbfe823/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f796f75747562652d7375627363726962652d6663316331632e7376673f7374796c653d666c61742d737175617265)](https://www.youtube.com/channel/UCjf2teVEuYVvvVC-gFZNq6w)

surrealdb.php
=============

[](#surrealdbphp)

The official SurrealDB SDK for PHP.

Documentation
-------------

[](#documentation)

View the SDK documentation [here](https://surrealdb.com/docs/integration/libraries/php).

How to install
--------------

[](#how-to-install)

You install the SurrealDB SDK via [Composer](https://getcomposer.org/). If you don't have Composer installed, you can download it [here](https://getcomposer.org/download/).

```
composer require surrealdb/surrealdb.php
```

Getting started
---------------

[](#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

[](#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](https://surrealdb.com/install) 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
-------------

[](#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

[](#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
------------

[](#contributing)

### Requirements

[](#requirements)

- PHP 8.4 or higher
- Composer
- SurrealDB 2.6.2 or higher

### Run static analysis

[](#run-static-analysis)

```
composer analyse
```

### Run tests

[](#run-tests)

```
composer test
```

### Directory Structure

[](#directory-structure)

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

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance70

Regular maintenance activity

Popularity35

Limited adoption so far

Community25

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 53.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~134 days

Recently: every ~121 days

Total

7

Last Release

20d ago

Major Versions

1.0.1 → 2.0.0-alpha.12026-06-26

PHP version history (2 changes)1.0.0-beta.1PHP >=8.2

2.0.0-alpha.1PHP >=8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/a22ee32d7586650244b476d5f8a0fb3a3d2ec9af98dc1eedf167f2f3c2c4c7b8?d=identicon)[surrealdb](/maintainers/surrealdb)

---

Top Contributors

[![welpie21](https://avatars.githubusercontent.com/u/14811347?v=4)](https://github.com/welpie21 "welpie21 (15 commits)")[![phughk](https://avatars.githubusercontent.com/u/6785919?v=4)](https://github.com/phughk "phughk (6 commits)")[![mcprog1](https://avatars.githubusercontent.com/u/49207091?v=4)](https://github.com/mcprog1 "mcprog1 (2 commits)")[![kearfy](https://avatars.githubusercontent.com/u/17960250?v=4)](https://github.com/kearfy "kearfy (2 commits)")[![adaliszk](https://avatars.githubusercontent.com/u/5189131?v=4)](https://github.com/adaliszk "adaliszk (1 commits)")[![tobiemh](https://avatars.githubusercontent.com/u/1588290?v=4)](https://github.com/tobiemh "tobiemh (1 commits)")[![LLNet](https://avatars.githubusercontent.com/u/7931918?v=4)](https://github.com/LLNet "LLNet (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/surrealdb-surrealdbphp/health.svg)

```
[![Health](https://phpackages.com/badges/surrealdb-surrealdbphp/health.svg)](https://phpackages.com/packages/surrealdb-surrealdbphp)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.9k556.2M21.5k](/packages/laravel-framework)[illuminate/database

The Illuminate Database package.

2.8k55.8M13.1k](/packages/illuminate-database)[spatie/laravel-medialibrary

Associate files with Eloquent models

6.2k45.4M704](/packages/spatie-laravel-medialibrary)[bavix/laravel-wallet

It's easy to work with a virtual wallet.

1.3k1.4M21](/packages/bavix-laravel-wallet)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k39.6k](/packages/matomo-matomo)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)