Oihana PHP Arango

SortTrait uses trait:short, \oihana\traits\SortDefaultTrait

Turns the textual `?sort=` grammar into an AQL `SORT` expression, and powers distance ordering via the `?near=` anchor.

?sort= grammar

A comma-separated list of keys; a leading - flips a key to descending. Each key is resolved through the model's AQL::SORTABLE whitelist (URL key → AQL field path); unknown keys are silently dropped. When no ?sort= is given, the model's SORT_DEFAULT applies.

?sort=name,-created   // SORT doc.name ASC, doc.created DESC

Distance ordering (?near=)

?near={ "key":"geo", "latitude":48.85, "longitude":2.35 } provides a reference point and exposes the synthetic sort key distance (Schema::DISTANCE). It is sort-only — it orders, it does not filter (pair it with a geo ?filter= to bound a radius). ?sort= stays the single ordering authority:

  • ?near=… alone (no ?sort=) defaults to SORT <distance> ASC.
  • ?near=…&sort=-distance orders farthest first.
  • ?near=…&sort=distance,name orders by distance then name (you pick the priority).
  • ?near=…&sort=name keeps name only — distance is not auto-appended.
  • ?sort=distance without ?near= is dropped (no anchor).

The reference point is bound (@lat / @lng) and the predicate uses DISTANCE(doc.<key>.latitude, doc.<key>.longitude, @lat, @lng), so it is index-accelerated by a two-field GeoIndex. Coordinates are bound only when a distance criterion is actually emitted, so the query never declares an unused bind variable.

Tags
author

Marc Alcaraz

since
1.0.0

Table of Contents

Properties

$sortable  : array<string|int, mixed>|null
The collection (map) of all the sortable fields.

Methods

bind()  : string
Bind a value to an AQL query variable.
bindCollection()  : string
Bind a collection name to an AQL query variable.
bindView()  : string
Bind the model's declared View name (`AQL::VIEW` block, {@see Search::NAME}) to an AQL query variable — collection bind parameters (`@@view`) are valid for View names as well.
initializeSortable()  : $this
Initialize the sortable array definition.
prepareSort()  : string|null
Prepare the AQL `SORT` expression from the `?sort=` grammar and, optionally, the `?near=` anchor.
prepareNear()  : string|null
Build the `DISTANCE(...)` expression for a `?near=` anchor and bind its coordinates.

Properties

$sortable

The collection (map) of all the sortable fields.

public array<string|int, mixed>|null $sortable = null

Methods

bind()

Bind a value to an AQL query variable.

public bind(mixed $value[, array<string|int, mixed> &$binds = [] ][, string|null $to = null ]) : string
Parameters
$value : mixed

The value to bind to the query.

$binds : array<string|int, mixed> = []

Reference to the array of existing bind variables.

$to : string|null = null

Optional name of the bind variable. If null, a unique name is generated.

Tags
throws
BindException

If the provided bind variable name is invalid.

Return values
string —

The formatted bind variable (including the "@" prefix as needed) for use in the query.

bindCollection()

Bind a collection name to an AQL query variable.

public bindCollection([array<string|int, mixed> &$binds = [] ][, array<string|int, mixed> $init = [] ]) : string

Prepares a bind variable for a collection name. Uses the collection defined in $init or falls back to $this->collection if none is provided.

Parameters
$binds : array<string|int, mixed> = []

Reference to the array of existing bind variables. If null, a new array is used.

$init : array<string|int, mixed> = []

Optional initialization array with keys:

  • Arango::COLLECTION => the collection name to bind
  • Arango::NAME => optional bind variable name
Tags
throws
BindException

If the bind variable name is invalid.

Return values
string —

The formatted bind variable representing the collection.

bindView()

Bind the model's declared View name (`AQL::VIEW` block, {@see Search::NAME}) to an AQL query variable — collection bind parameters (`@@view`) are valid for View names as well.

public bindView([array<string|int, mixed> &$binds = [] ]) : string
Parameters
$binds : array<string|int, mixed> = []

Reference to the array of existing bind variables.

Tags
throws
BindException

If the bind variable name is invalid.

Return values
string —

The formatted bind variable representing the View.

initializeSortable()

Initialize the sortable array definition.

public initializeSortable([array<string|int, mixed> $init = [] ]) : $this
Parameters
$init : array<string|int, mixed> = []
Return values
$this

prepareSort()

Prepare the AQL `SORT` expression from the `?sort=` grammar and, optionally, the `?near=` anchor.

public prepareSort([array<string|int, mixed> $init = [] ][, array<string|int, mixed>|null $sortable = null ][, string $docRef = AQL::DOC ][, array<string|int, mixed>|null &$binds = null ]) : string|null

Each comma-separated criterion in Arango::SORT is resolved against $sortable (URL key → AQL field path); a leading - makes it descending. The synthetic distance key (Schema::DISTANCE) is resolved from Arango::NEAR and only honored when $binds is provided (so the reference point can be bound).

Parameters
$init : array<string|int, mixed> = []

Per-call parameters. Reads Arango::SORT (grammar) and Arango::NEAR (geo anchor).

$sortable : array<string|int, mixed>|null = null

URL-key → field-path whitelist. Defaults to $this->sortable.

$docRef : string = AQL::DOC

The document variable the fields hang off (default doc).

$binds : array<string|int, mixed>|null = null

Bind variables, populated by reference. Required to enable distance/?near= sorting.

Tags
throws
BindException

When a bound coordinate cannot be registered.

ValidationException

When a sort key (open mode) or the ?near= key is not a safe attribute name.

example

Plain field sort

$model->prepareSort( [ Arango::SORT => 'name,-created' ] ) ;
// "doc.name ASC, doc.created DESC"

Distance sort (nearest first) via ?near=

$binds = [] ;
$model->prepareSort
(
    [ Arango::NEAR => [ FilterParam::KEY => 'geo' , 'latitude' => 48.85 , 'longitude' => 2.35 ] ] ,
    binds : $binds
) ;
// "DISTANCE(doc.geo.latitude, doc.geo.longitude, @lat, @lng) ASC"

Distance then name

$model->prepareSort
(
    [ Arango::SORT => 'distance,name' , Arango::NEAR => [ ... ] ] ,
    binds : $binds
) ;
// "DISTANCE(...) ASC, doc.name ASC"
Return values
string|null —

The SORT body (without the SORT keyword), or an empty string when nothing sorts.

prepareNear()

Build the `DISTANCE(...)` expression for a `?near=` anchor and bind its coordinates.

protected prepareNear(array<string|int, mixed> $near, array<string|int, mixed>|null &$binds[, string $docRef = AQL::DOC ]) : string|null

Reads the { key, latitude, longitude } payload, validates the attribute key against injection (assertAttributeName()), binds the reference point, and returns the AQL distance expression. Returns null when the key is missing or the coordinates are incomplete.

Parameters
$near : array<string|int, mixed>

The ?near= payload ({ key, latitude, longitude }), already array-checked by the caller.

$binds : array<string|int, mixed>|null

Bind variables, populated by reference.

$docRef : string = AQL::DOC

The document variable the fields hang off.

Tags
throws
BindException

When a bound coordinate cannot be registered.

ValidationException

When the key is not a safe attribute name.

Return values
string|null —

DISTANCE(doc.<key>.latitude, doc.<key>.longitude, @lat, @lng) or null.

On this page

Search results