Data Types

The PHP SDK translates all SurrealQL datatypes into native PHP types, or a custom implementation. This document describes all datatypes, and links to their respective documentation.

Data Types overview

RecordId

When you receive a RecordId from SurrealDB, it will always be represented as a RecordId class. This class holds a tb and id field, representing the table name, and a unique identifier for the record on that table. A RecordId can be converted into a string, and will be represented as such when it’s converted to JSON.

Signature
new RecordId(string $tb, string|int|array $id)

Working with a RecordId

Constructing
// table is "person"
// unique identifier on the table is "john"
$rid = new RecordId("person", "john");

Extracting data
// Simple
$rid = new RecordId("person", "john");
$rid->tb // "person"
$rid->id // "john"

// Complex
$rid = new RecordId("recording", ["city" => "London", "data" => 123 ]);

$rid->id         // [ "city" => "London", "data" => 123 ]
$rid->id["city"] // "London"
$rid->id["data"] // 123

Convert to String

The PHP SDK flawlessly and efficiently handles escaping the tb and id parts in Record Id’s into their string counterparts. Below are some examples

Simple
$rid = (new RecordId("table", 123))->toString();
// 'table:123'
$rid = (new RecordId("table", "abc"))->toString();
// 'table:abc'

Complex characters
$rid = (new RecordId("table", "123"))->toString();
// 'table:⟨123⟩'
$rid = (new RecordId("table", "123withletters"))->toString();
// 'table:123withletters'
$rid = (new RecordId("table", "complex-string"))->toString();
// 'table:⟨complex-string⟩'
$rid = (new RecordId("table-name", 123))->toString();
// '⟨table-name⟩:123'

Objects and Arrays
$rid = (new RecordId("table", ["city" => "London"]))->toString();
// 'table:{ city: "London" }'
$rid = (new RecordId("table", ["London"]))->toString();
// 'table:["London"]'

Send back string

If you need to send back a Record Id in string format, you can do so with the StringRecordId class.

We do not implement the parsing of Record Ids in the PHP SDK, as that would mean that we need to be able to parse any SurrealQL value, which comes with a cost. Instead you can send it over as a string with StringRecordId, allowing the server to handle the parsing.

new StringRecordId("person:john");

Geometry

When a Geometry is sent back from SurrealDB, be it a Point, Line, Polygon, MultiPoint, MultiLine, MultiPolygon or Collection, it will be represented as a derivative of the Geometry class.

Methods

Below, are all the methods implemented across all geometry derivatives.

->toJSON()

Used to convert a geometry to a GeoJSON representation

Signature
Geometry->toJson();

Example
$line = new GeometryLine([
    new GeometryPoint([1, 2]),
    new GeometryPoint([3, 4]),
]);

$line->toJson();                    // '{ type: "LineString", coordinates: [ [1, 2], [3, 4] ] }'
json_encode($line);                 // '{ type: "LineString", coordinates: [ [1, 2], [3, 4] ] }'

->is()

Used to convert a check if geometry X is exactly equal to geometry Y

Signature
Geometry->is(Geometry $geometry)

Example
$point1 = new GeometryPoint([1, 2]);
$point2 = new GeometryPoint([3, 4]);
$line = new GeometryLine([$point1, $point2]);

$point1->is($point1);      // true
$point1->is($point2);      // false
$point1->is($line);        // false

// Checks the inner values, does not need to be the same instance
$duplicate = new GeometryPoint([1, 2]);
$point1->is($duplicate);   // true

->clone()

Used to deeply clone a geometry. Creates a new replica of the original instance, but changing the new instance won’t affect the other.

Signature
Geometry->clone()

Properties

->coordinates

A getter property, representing the coordinates as shown in GeoJSON format for X Geometry

Signature
Geometry.coordinates

Derivatives

GeometryPoint

A point in space, made up of a lat and lon coordinate, automatically converted to a float.

Signature
new GeometryPoint([int|float|Decimal $lat, int|float|Decimal $lon]);

GeometryLine

A line, made up of two or more points

Signature
new GeometryLine([GeometryPoint, GeometryPoint, ...GeometryPoint[]]);

GeometryPolygon

A polygon, made up of self-closing lines

Note: The lines inside the polygon will automatically be closed if not already, meaning that the last point will be the same as the first.

Signature
new GeometryPolygon([GeometryLine, ...GeometryLine[]]);

GeometryMultiPoint

A collection of one or more points

Signature
new GeometryMultiPoint([GeometryPoint, ...GeometryPoint[]]);

GeometryMultiLine

A collection of one or more lines

Signature
new GeometryMultiLine([GeometryLine, ...GeometryLine[]]);

GeometryMultiPolygon

A collection of one or more polygons

Signature
new GeometryMultiPolygon([GeometryPolygon, ...GeometryPolygon[]]);

GeometryCollection

A collection of one or more Geometry derivatives

Signature
new GeometryCollection([Geometry, ...Geometry[]]);

Decimal

Because PHP does not support Decimals natively, our SDK represents them in a Decimal class as a string. This means if you want to work with Decimals, you will need to use an external library for this.

Signature
new Decimal(string|float|Decimal $decimal);

Converting to string

$decimal = new Decimal("123.456");
decimal->toString(); // "123.456"

Converting to JSON

A Decimal will be represented as a string in JSON to perserve accuracy

$decimal = new Decimal("123.456");
$decimal->toJson();                  // "123.456"
json_encode(decimal);                // "123.456"

Table

When you get a table name sent back from SurrealDB, it will be represented as a Table class.

Signature
new Table(string $table);

Converting to string

$table = new Table("table");
$table->toString();              // "table"
```Composer package

### Converting to JSON

A `Table` will be represented as a string in JSON

```php
$table = new Table("table");
$table->jsonSerializable();      // "table"
json_encode($table);             // "table"