Oihana PHP Arango

GroupTrait

Translates the high-level {@see Arango::GROUP} spec ({@see Group}) into the raw `COLLECT` spec consumed by {@see \oihana\arango\db\operations\aqlCollect()} and {@see \oihana\arango\db\operations\aqlCollectReturn()} in {@see \oihana\arango\models\traits\queries\ListQueryTrait::buildListQuery()}.

It is the COLLECT counterpart of FacetTrait, reusing the same engines:

  • FacetAggregator for the aggregate functions (sum→SUM, …),
  • the alt engine (alterExpression()) for grouping-key transforms,
  • the key() helper to prefix fields with the document reference.

A raw Arango::COLLECT spec is passed through untouched when no Arango::GROUP is supplied, so power users keep full control.

Tags
see
GroupTrait::prepareCollect()

The entry point.

Table of Contents

Properties

$groupable  : array<string, string>|null
Optional whitelist/mapping of groupable dimensions: `urlKey => fieldPath`.

Methods

initializeGroupable()  : static
Initializes the {@see GroupTrait::$groupable} whitelist from the model options.
prepareCollect()  : array<string|int, mixed>
Resolves the `COLLECT` spec for a list query.
prepareGroupSort()  : string|null
Builds the `SORT` clause applied to a grouped result, from {@see Group::SORT}.
collectAggregate()  : array<string|int, mixed>
Builds the `AQL::AGGREGATE` map from {@see Group::AGG}.
collectAssign()  : array<string|int, mixed>
Builds the `AQL::ASSIGN` map from {@see Group::BY} and {@see Group::ALT}.
normalizeAggregate()  : array{0: ?string, 1: ?string}
Normalizes an aggregate definition into a `[ code, field ]` pair.
normalizeGroupFields()  : array<string, string>
Normalizes {@see Group::BY} into a `[ varName => field ]` map.

Properties

$groupable

Optional whitelist/mapping of groupable dimensions: `urlKey => fieldPath`.

public array<string, string>|null $groupable = null

When set, only whitelisted Group::BY keys are allowed and each resolves to its real field path (decoupling the public group key from the internal attribute, like SortTrait::$sortable). When null, grouping is open but every field is still validated against AQL injection via assertAttributeName().

Methods

initializeGroupable()

Initializes the {@see GroupTrait::$groupable} whitelist from the model options.

public initializeGroupable([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []

The model options (Arango::GROUPABLE).

Return values
static

prepareCollect()

Resolves the `COLLECT` spec for a list query.

public prepareCollect([array<string|int, mixed> $init = [] ][, string $docRef = AQL::DOC ]) : array<string|int, mixed>

Translates a friendly Arango::GROUP spec (Group::BY, Group::AGG, Group::COUNT, Group::ALT) into the raw aqlCollect() keys. Falls back to the raw Arango::COLLECT spec (or an empty array) when no group is requested.

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

The list query options.

$docRef : string = AQL::DOC

The document reference grouping fields are read from.

Tags
throws
UnsupportedOperationException
ValidationException
Return values
array<string|int, mixed> —

The raw COLLECT spec (AQL::ASSIGN, AQL::AGGREGATE, AQL::WITH_COUNT).

prepareGroupSort()

Builds the `SORT` clause applied to a grouped result, from {@see Group::SORT}.

public prepareGroupSort([array<string|int, mixed> $init = [] ]) : string|null

The sort operates on group/aggregate variable names (never on doc, which is out of scope after COLLECT): a CSV with a leading - for descending, e.g. '-count' → count DESC, 'category,-total' → category ASC, total DESC.

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

The list query options.

Return values
string|null —

The inner sort expression, or null when none.

collectAggregate()

Builds the `AQL::AGGREGATE` map from {@see Group::AGG}.

private collectAggregate(array<string|int, mixed> $group, string $docRef) : array<string|int, mixed>
Parameters
$group : array<string|int, mixed>

The group spec.

$docRef : string

The document reference.

Tags
throws
ValidationException
Return values
array<string|int, mixed> —

[ outName => 'FN(doc.field)' ].

collectAssign()

Builds the `AQL::ASSIGN` map from {@see Group::BY} and {@see Group::ALT}.

private collectAssign(array<string|int, mixed> $group, string $docRef) : array<string|int, mixed>
Parameters
$group : array<string|int, mixed>

The group spec.

$docRef : string

The document reference.

Tags
throws
UnsupportedOperationException
ValidationException
Return values
array<string|int, mixed> —

[ varName => 'doc.field' | 'FN(doc.field)' ].

normalizeAggregate()

Normalizes an aggregate definition into a `[ code, field ]` pair.

private normalizeAggregate(mixed $definition) : array{0: ?string, 1: ?string}

Accepts 'sum:amount' (string) or ['sum','amount'] (list).

Parameters
$definition : mixed
Return values
array{0: ?string, 1: ?string}

normalizeGroupFields()

Normalizes {@see Group::BY} into a `[ varName => field ]` map.

private normalizeGroupFields(mixed $by) : array<string, string>
  • CSV string 'category,status' → [ 'category' => 'category', 'status' => 'status' ].
  • list ['category','status'] → same.
  • assoc ['year' => 'created'] → kept as-is.

Dotted fields yield underscore variable names (address.city → address_city).

Parameters
$by : mixed
Return values
array<string, string>
On this page

Search results