Download the PHP package surrealdb/laravel without Composer

SurrealDB Laravel

Laravel integration for the official SurrealDB PHP SDK and the Surqlize ORM.

This package gives Laravel applications a publishable configuration file, service-container bindings, facades, an Artisan schema command, and testing helpers. Query execution and database protocol behavior are delegated to surrealdb/surrealdb.php; ORM models, query compilation, graph relations, and schema definitions are delegated to surqlize/surqlize.

Requirements

Installation

Install the package with Composer:

While the SDK and ORM are still in active development, local workspace installs can use path repositories:

Publish the configuration:

Configuration

The package intentionally keeps SDK and ORM configuration separate:

• config/surrealdb.php configures the raw SurrealDB PHP SDK client.
• config/surqlize.php configures Surqlize ORM behavior.

config/surrealdb.php reads these common environment variables:

If SURREALDB_USERNAME is set, the package uses SDK RootAuth by default. For scoped authentication, set SURREALDB_AUTH_MODE to namespace, database, record, bearer, token, or none, then fill the matching keys in the published config.

The SDK config supports named connections:

config/surqlize.php contains the ORM model list and executor binding:

Service Container

Laravel auto-discovers two service providers:

• SurrealDB\Laravel\SurrealDBServiceProvider owns SDK configuration, client construction, and the surrealdb container alias.
• SurrealDB\Laravel\SurqlizeServiceProvider owns ORM configuration, schema commands, Surqlize's executor binding, and ConnectionManager setup.

The SDK provider binds:

• SurrealDB\SDK\Surreal and the surrealdb container alias for the raw SDK client.
• SurrealDB\Laravel\SurrealDBManager plus the surrealdb.manager and surrealdb.connection aliases for Laravel-style lifecycle helpers.

The ORM provider binds:

• SurrealDB\SDK\Contracts\QueryExecutor for Surqlize query execution.
• Surqlize\Model\SchemaManager for schema definitions and application.
• SurrealDB\Laravel\SurqlizeManager and the surqlize container alias for Laravel-friendly helpers.

The ORM provider also registers Surqlize's global ConnectionManager with a lazy executor that resolves the configured surqlize.executor binding only when a query executes. By default, that binding points at surrealdb.connection, so Surqlize model queries use the Laravel manager and connect lazily.

Models

Surqlize models are not Eloquent models. They extend Surqlize\Model\Model and use Surqlize attributes:

Register models that should participate in schema commands:

Schemas

Schemas implement Surqlize\Model\SchemaContract:

Preview schema statements:

Apply schema statements:

Queries

Use Surqlize's model APIs:

No manual executor is needed for normal Laravel usage. The package configures Surqlize to use the Laravel-managed SurrealDB executor:

Use the raw SDK when you need lower-level access:

Use the Laravel manager facade when you want lifecycle helpers around the same SDK client:

The Surqlize facade exposes schema and transaction helpers:

Surqlize::transaction() uses Surqlize's executor-based SurrealQL transaction batching. SDK-native transaction IDs are not exposed through the Laravel facade yet because they depend on WebSocket transport and server feature support.

Testing

Use the package testing trait to reset Surqlize's global caches:

For unit tests, pass a fake QueryExecutor to Surqlize queries or call useSurqlizeExecutor() from the trait.

You can also fake the Laravel-managed executor:

Named fakes are scoped by connection:

Development

Notes

• The SDK v2 API is still alpha, so expect dependency constraints to tighten as the SDK stabilizes.
• Laravel singleton scope follows the application container: normally once per request under PHP-FPM, and longer-lived under Octane, queue workers, or long-running commands.
• Surqlize currently has a singleton ConnectionManager. Use per-query withExecutor() or explicit executor: arguments when you need multiple executors in the same process.
• Live queries, sessions, and native SDK transactions require WebSocket support and depend on the underlying SurrealDB server version.