Oihana PHP Arango

HasFilterGeo uses trait:short, \oihana\logging\LoggerTrait

This trait defines the geospatial filter helpers.

Configure

Declare a FilterType::GEO key in the model (Documents) definition. The value stored under that key is expected to be a Schema.org GeoCoordinates-shaped object, i.e. <key>.latitude and <key>.longitude.

AQL::FILTERS =>
[
    'geo' => FilterType::GEO ,
]

Use

The distance operator filters documents by their distance (in meters) to a reference point. The radius bounds reuse the min / max keys, exactly like between:

// within 5 km
?filter={ "key":"geo", "op":"distance", "val":{ "latitude":48.85, "longitude":2.35 }, "max":5000 }
// → DISTANCE(doc.geo.latitude, doc.geo.longitude, @lat, @lng) <= @max

// ring between 1 km and 5 km
?filter={ "key":"geo", "op":"distance", "val":{ "latitude":48.85, "longitude":2.35 }, "min":1000, "max":5000 }

DISTANCE reads two scalar attributes, so the predicate is index-accelerated when a two-field GeoIndex is declared over <key>.latitude / <key>.longitude (geoJson: false).

Table of Contents

Methods

bind()  : string
Bind a value to an AQL query variable.
bindCollection()  : string
Bind a collection name to an AQL query variable.
binder()  : callable(mixed): string
Returns a binder over `$binds` — the callable {@see Arango::BINDER} carries down to the `alt` engine, so a parameter that arrived with a request becomes a bound value instead of text written into the query.
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.
prepareFilterGeo()  : string|null
Prepares the filter clause for a geospatial attribute.

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.

binder()

Returns a binder over `$binds` — the callable {@see Arango::BINDER} carries down to the `alt` engine, so a parameter that arrived with a request becomes a bound value instead of text written into the query.

public binder([array<string|int, mixed>|null &$binds = null ]) : callable(mixed): string

⚠ Deliberately a function () use ( &$binds ) and not an arrow function: fn() captures by value, so the bind would land in a copy and the query would declare a parameter nothing ever fills. That mistake costs a 400 from the server and is invisible to any assertion made on the emitted AQL — which is why the closure is built here, once, rather than at each reading point.

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

Reference to the array of existing bind variables; a null is initialised in place.

Return values
callable(mixed): string —

A callable registering a value and returning its @name.

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.

prepareFilterGeo()

Prepares the filter clause for a geospatial attribute.

protected prepareFilterGeo([array<string|int, mixed> $init = [] ][, array<string|int, mixed>|null &$binds = null ][, string $doc = AQL::DOC ]) : string|null
Parameters
$init : array<string|int, mixed> = []
$binds : array<string|int, mixed>|null = null
$doc : string = AQL::DOC
Tags
throws
BindException
Return values
string|null —

The AQL condition, or null when the request names an operator this filter cannot honour, or a value that is not a point. null is what the composition layer knows how to drop; an empty string is not.

On this page

Search results