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, such as <future> { ... }. 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().

Class	Constructor
`GeometryPoint`	`new GeometryPoint(float $longitude, float $latitude)`
`GeometryLine`	`new GeometryLine(GeometryPoint $first, GeometryPoint ...$rest)`
`GeometryPolygon`	`new GeometryPolygon(GeometryLine $exterior, GeometryLine ...$interior)`
`GeometryMultiPoint`	`new GeometryMultiPoint(GeometryPoint $first, GeometryPoint ...$rest)`
`GeometryMultiLine`	`new GeometryMultiLine(GeometryLine $first, GeometryLine ...$rest)`
`GeometryMultiPolygon`	`new GeometryMultiPolygon(GeometryPolygon $first, GeometryPolygon ...$rest)`
`GeometryCollection`	`new 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();

RecordId

StringRecordId

Table

DateTime

Duration

Decimal

Uuid

Range and RecordIdRange

Set

Bytes

None

File

Future

Note

Geometry

See also

`RecordId`

`StringRecordId`

`Table`

`DateTime`

`Duration`

`Decimal`

`Uuid`

`Range` and `RecordIdRange`

`Set`

`Bytes`

`None`

`File`

`Future`