# 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` {#recordid}

A record identifier: a table name and an ID.

```php title="Constructor"
new RecordId(string $table, string|int|array|object $id)
RecordId::from(string $table, string|int|array|object $id)
```

```php
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` {#stringrecordid}

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

```php title="Constructor"
new StringRecordId(StringRecordId|RecordId|string $id)
```

```php
use SurrealDB\SDK\Types\StringRecordId;

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

## `Table` {#table}

A table reference.

```php title="Constructor"
new Table(string $name)
```

```php
use SurrealDB\SDK\Types\Table;

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

## `DateTime` {#datetime}

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

```php title="Constructor and factories"
new DateTime(int $seconds = 0, int $nanoseconds = 0)
DateTime::fromString(string $iso)
DateTime::fromDateTime(DateTimeInterface $dateTime)
DateTime::now()
DateTime::epoch()
```

```php
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` {#duration}

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

```php title="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
```

```php
use SurrealDB\SDK\Types\Duration;

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

## `Decimal` {#decimal}

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

```php title="Constructor"
new Decimal(Decimal|BigDecimal|string|int|float $value)
```

```php
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` {#uuid}

A universally unique identifier, backed by `symfony/uid`.

```php title="Factories"
Uuid::v4()                      // random
Uuid::v7()                      // time-ordered
Uuid::fromString(string $uuid)
Uuid::fromBytes(string $bytes)
```

```php
use SurrealDB\SDK\Types\Uuid;

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

## `Range` and `RecordIdRange` {#range}

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.

```php title="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)
```

```php
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` {#set}

An array whose items are deduplicated.

```php title="Constructor"
new Set(iterable $items = [])
```

```php
use SurrealDB\SDK\Types\Set;

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

## `Bytes` {#bytes}

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

```php title="Constructor and factory"
new Bytes(string $bytes)
Bytes::fromBase64(string $base64)
```

```php
use SurrealDB\SDK\Types\Bytes;

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

## `None` {#none}

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

```php
use SurrealDB\SDK\Types\None;

$none = None::instance();
```

## `File` {#file}

A reference to a file stored in a bucket.

```php title="Constructor"
new File(string $bucket, string $key)
```

```php
use SurrealDB\SDK\Types\File;

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

## `Future` {#future}

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

```php title="Constructor"
new Future(string $body)
```

```php
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 {#geometry}

Classes for each [GeoJSON geometry type](/docs/reference/query-language/language-primitives/data-types/geometries.md). 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)` |

```php
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

- [Data types concept](/docs/reference/php/v2/concepts/data-types.md) for the type mapping and guidance
- [SurrealQL data model](/docs/reference/query-language/language-primitives/data-types.md) for the database type system