Oihana PHP Arango

HasFacetField

Builds the AQL filter fragment for a {@see Facet::FIELD} facet: a comparison on a scalar document property `doc.<property>`, driven by an operator (`op`) that reuses the filter vocabulary ({@see FilterComparator}: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `like`, `nlike`, `match` default, `nmatch`).

The compact multi-select syntax is preserved: comma-separated values are OR-ed, and a leading - negates a value by switching the operator to its negative counterpart (match→nmatch, eq→ne, like→nlike) — which also flips the group to AND. Composed into the model via FacetTrait.

Tags
see
FacetTrait::prepareFacets()

The dispatcher that invokes this builder.

Table of Contents

Methods

prepareFacetField()  : string
Prepares a field facet (scalar property comparison, `=~` match by default).
negatedComparator()  : string|null
Returns the negative counterpart of an operator code, or null when it has none (ordering operators, already-negative operators, …).
prepareFacetFieldBetween()  : string
Builds an inclusive `between` (range) field facet: `(LEFT >= @min && LEFT <= @max)`.

Methods

prepareFacetField()

Prepares a field facet (scalar property comparison, `=~` match by default).

protected prepareFacetField(string $key, mixed $value, array<string|int, mixed> &$binds, array<string|int, mixed> $facet, string $doc) : string

The operator defaults to match (regex =~, backward compatible). It can be set in the facet definition (Facet::OP) or overridden per request with an {op, val} object. Operator codes reuse FilterComparator.

Parameters
$key : string

The facet key (also the default document property).

$value : mixed

A CSV string, a list, or an {op, val} object selecting the operator per request.

$binds : array<string|int, mixed>

The bind variables, populated by reference.

$facet : array<string|int, mixed>

The facet definition (Facet::PROPERTY, Facet::OP).

$doc : string

The document reference the property is read from.

Tags
throws
BindException
UnsupportedOperationException
ValidationException
example

Set the facetable definition in the model (operator optional, defaults to match; it can also be overridden per request) :

Arango::FACETS =>
[
    Prop::WITH_STATUS => [ Facet::TYPE => Facet::FIELD ] ,                                  // =~ (default)
    Prop::ID          => [ Facet::TYPE => Facet::FIELD , Facet::PROPERTY => '_key' , Facet::OP => FilterComparator::EQ ] , // ==
    Prop::PRICE       => [ Facet::TYPE => Facet::FIELD , Facet::OP => FilterComparator::GE ] // >=
]

Default operator — regex match, comma-separated values are OR-ed :

?facets={"withStatus":"under_review"}            // (doc.withStatus =~ @0)
?facets={"withStatus":"draft,under_review"}      // (doc.withStatus =~ @0 || doc.withStatus =~ @1)

Negation — a leading - switches to the negative operator and ANDs the group :

?facets={"withStatus":"-draft"}                  // (doc.withStatus !~ @0)
?facets={"withStatus":"-under_review,-draft"}    // (doc.withStatus !~ @0 && doc.withStatus !~ @1)

Pick the operator per request with {op, val} :

?facets={"withStatus":{"op":"eq","val":"draft"}} // (doc.withStatus == @0)   exact, not regex
?facets={"price":{"op":"ge","val":100}}          // (doc.price >= @0)
?facets={"name":{"op":"like","val":"jo%"}}       // (doc.name LIKE @0)
?facets={"withStatus":{"op":"eq","val":"-draft"}}// (doc.withStatus != @0)   negation, generic

Supported operators: eq, ne, gt, ge, lt, le, like, nlike, match (default), nmatch. An unknown op falls back to match.

Return values
string

negatedComparator()

Returns the negative counterpart of an operator code, or null when it has none (ordering operators, already-negative operators, …).

private negatedComparator(string $op) : string|null
Parameters
$op : string
Return values
string|null

prepareFacetFieldBetween()

Builds an inclusive `between` (range) field facet: `(LEFT >= @min && LEFT <= @max)`.

private prepareFacetFieldBetween(string $key, array<string|int, mixed> $value, array<string|int, mixed> &$binds, array<string|int, mixed> $facet, string $doc, mixed $alt) : string

The compared property is alt-aware (the key-side chain wraps doc.<property>). An omitted bound drops its side (one-sided range), mirroring the number/string ?filter= semantics; both omitted yields an empty fragment.

Parameters
$key : string

The facet key.

$value : array<string|int, mixed>

The request object (min, max).

$binds : array<string|int, mixed>

The bind variables, populated by reference.

$facet : array<string|int, mixed>

The facet definition (Facet::PROPERTY).

$doc : string

The document reference.

$alt : mixed

The resolved alt parameter (request over definition).

Tags
throws
BindException
UnsupportedOperationException
ValidationException
Return values
string
On this page

Search results