• Start
Sign In

v2 (alpha)

/

API Reference

Data types

Reference for the SurrealQL value classes in version 2 of the PHP SDK, in the SurrealDB\SDK\Types namespace.

Version 2 represents SurrealQL types that PHP lacks with value classes in the SurrealDB\SDK\Types namespace. Every class extends the abstract Value and provides escape() (the inline SurrealQL form), jsonSerialize(), equals(), and __toString().

RecordId

A record identifier: a table name and an ID.

Constructor
new RecordId(string $table, string|int|array|object $id)
RecordId::from(string $table, string|int|array|object $id)
use SurrealDB\SDK\Types\RecordId;

$id = new RecordId('person', 'tobie');
echo $id->table; // "person"
echo $id->id;    // "tobie"

$composite = new RecordId('temperature', ['city' => 'London', 'time' => 1700000000]);

The ID can be a string, integer, array, or object. The table and id properties expose the parts.

StringRecordId

A record ID kept as a raw string. Use it to pass an ID through verbatim and let the server parse it.

Constructor
new StringRecordId(StringRecordId|RecordId|string $id)
use SurrealDB\SDK\Types\StringRecordId;

$db->select(new StringRecordId('person:tobie'))->execute();

Table

A table reference.

Constructor
new Table(string $name)
use SurrealDB\SDK\Types\Table;

$table = new Table('person');
echo $table->name; // "person"

DateTime

A datetime with nanosecond precision, stored as a (seconds, nanoseconds) pair.

Constructor and factories
new DateTime(int $seconds = 0, int $nanoseconds = 0)
DateTime::fromString(string $iso)
DateTime::fromDateTime(DateTimeInterface $dateTime)
DateTime::now()
DateTime::epoch()
use SurrealDB\SDK\Types\DateTime;

$now = DateTime::now();
$parsed = DateTime::fromString('2024-01-15T12:00:00.123456789Z');

$native = $now->toDateTimeImmutable(); // microsecond precision
$iso = $now->toIso();

Duration

A duration with nanosecond precision, rendered with SurrealQL's compact syntax such as 1h30m.

Constructor and factories
new Duration(int $seconds = 0, int $nanoseconds = 0)
Duration::fromString(string $input)
Duration::seconds(int $value)   // also: nanoseconds, microseconds, milliseconds, minutes, hours, days, weeks, years
use SurrealDB\SDK\Types\Duration;

$ttl = Duration::fromString('1h30m');
$combined = Duration::hours(1)->add(Duration::minutes(30));
echo $combined->totalNanoseconds();

Decimal

An arbitrary-precision decimal backed by Brick\Math\BigDecimal. Construct from a string to keep precision.

Constructor
new Decimal(Decimal|BigDecimal|string|int|float $value)
use SurrealDB\SDK\Types\Decimal;

$price = new Decimal('19.99');
$total = $price->multipliedBy(3); // 59.97
echo $total; // "59.97"

Arithmetic methods include plus(), minus(), multipliedBy(), dividedBy(), abs(), and negated().

Uuid

A universally unique identifier, backed by symfony/uid.

Factories
Uuid::v4()                      // random
Uuid::v7()                      // time-ordered
Uuid::fromString(string $uuid)
Uuid::fromBytes(string $bytes)
use SurrealDB\SDK\Types\Uuid;

$id = Uuid::v7();
echo $id;            // canonical RFC 4122 string
$binary = $id->toBytes();

Range and RecordIdRange

A Range is a bounded or open interval. A RecordIdRange is a range of record IDs in a table. Bounds are BoundIncluded, BoundExcluded, or null for an open end.

Constructors
new Range(BoundIncluded|BoundExcluded|null $begin, BoundIncluded|BoundExcluded|null $end)
new RecordIdRange(string $table, $begin, $end)
new BoundIncluded(mixed $value)
new BoundExcluded(mixed $value)
use SurrealDB\SDK\Types\RecordIdRange;
use SurrealDB\SDK\Types\BoundIncluded;
use SurrealDB\SDK\Types\BoundExcluded;

// person:1..=100
$range = new RecordIdRange('person', new BoundIncluded(1), new BoundIncluded(100));
$slice = $db->select($range)->execute();

Set

An array whose items are deduplicated.

Constructor
new Set(iterable $items = [])
use SurrealDB\SDK\Types\Set;

$tags = new Set(['a', 'b', 'a']); // ['a', 'b']

Bytes

A binary value. Construct from a raw string or a base64url string.

Constructor and factory
new Bytes(string $bytes)
Bytes::fromBase64(string $base64)
use SurrealDB\SDK\Types\Bytes;

$bytes = new Bytes($raw);
echo $bytes->toBase64();

None

The SurrealQL NONE value, distinct from null. It is a singleton.

use SurrealDB\SDK\Types\None;

$none = None::instance();

File

A reference to a file stored in a bucket.

Constructor
new File(string $bucket, string $key)
use SurrealDB\SDK\Types\File;

$file = new File('avatars', '/tobie.png');
echo $file->bucket; // "avatars"
echo $file->key;    // "/tobie.png"

Future

An uncomputed SurrealQL [future](/docs/reference/query-language/language-primitives/data-types/futures), such as ` { ... }`. The body is the SurrealQL expression to evaluate.

Constructor
new Future(string $body)
use SurrealDB\SDK\Types\Future;

$future = new Future('{ created_at + 1w }');
echo $future->body;
Note

Futures were removed in SurrealDB 3.0. This type is retained for compatibility with older servers and parity with the JavaScript SDK, and is deprecated.

Geometry

Classes for each GeoJSON geometry type. They all extend the abstract Geometry, which provides toGeoJson(), is(), and the static Geometry::fromGeoJson().

ClassConstructor
GeometryPointnew GeometryPoint(float $longitude, float $latitude)
GeometryLinenew GeometryLine(GeometryPoint $first, GeometryPoint ...$rest)
GeometryPolygonnew GeometryPolygon(GeometryLine $exterior, GeometryLine ...$interior)
GeometryMultiPointnew GeometryMultiPoint(GeometryPoint $first, GeometryPoint ...$rest)
GeometryMultiLinenew GeometryMultiLine(GeometryLine $first, GeometryLine ...$rest)
GeometryMultiPolygonnew GeometryMultiPolygon(GeometryPolygon $first, GeometryPolygon ...$rest)
GeometryCollectionnew GeometryCollection(Geometry $first, Geometry ...$rest)
use SurrealDB\SDK\Types\GeometryPoint;
use SurrealDB\SDK\Types\GeometryLine;

$point = new GeometryPoint(-0.118092, 51.509865);
$line = new GeometryLine(
    new GeometryPoint(0, 0),
    new GeometryPoint(1, 1),
);

$geojson = $line->toGeoJson();

See also

Was this page helpful?

Previous

Query builders

Next

Utilities