Oihana PHP Arango

InjectFilterTrait

Provides filter injection helpers for ArangoDB-based controllers.

Allows programmatic injection of filters that are transparently merged with user-provided URL filters. Injected filters do NOT appear in the response URL — they are passed via the $init array, not via query params.

Usage in a controller:

public function list( ?Request $request , ?Response $response , array $args = [] , array $init = [] ) :mixed
{
    $this->injectFilter( $init , 'userId' , $userKey ) ; // $init is passed by reference
    return parent::list( $request , $response , $args , $init ) ;
}

Overrides prepareFilter() to merge URL filters with injected filters.

Tags
see
FilterParam

for filter parameter keys (key, op, val, alt)

FilterComparator

for comparison operators (eq, ne, gt, ge, lt, le, like, in, etc.)

author

Marc Alcaraz

Table of Contents

Constants

INJECTED_FILTERS  : string = '__injectedFilters'
Init key for injected filters (internal, not exposed to user).

Methods

injectFilter()  : void
Injects a single filter into the `$init` array — modified in place.
injectFilterGroup()  : void
Injects a logic group into the `$init` array — modified in place.
injectFilters()  : void
Injects multiple filters into the `$init` array at once — modified in place.
prepareFilter()  : array<string|int, mixed>|null
Overrides PrepareFilter::prepareFilter to merge URL filters with injected filters.

Constants

INJECTED_FILTERS

Init key for injected filters (internal, not exposed to user).

protected string INJECTED_FILTERS = '__injectedFilters'

Methods

injectFilter()

Injects a single filter into the `$init` array — modified in place.

protected injectFilter(array<string|int, mixed> &$init, string $key, mixed $value[, string $op = FilterComparator::EQ ][, string|null $alt = null ]) : void

The filter will be transparently merged with any user-provided URL filters in prepareFilter() without appearing in the response URL.

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

The init array to enrich (passed by reference).

$key : string

The field name to filter on.

$value : mixed

The filter value.

$op : string = FilterComparator::EQ

The comparison operator (default: FilterComparator::EQ).

$alt : string|null = null

Optional alteration function (e.g., 'lower', 'length').

injectFilterGroup()

Injects a logic group into the `$init` array — modified in place.

protected injectFilterGroup(array<string|int, mixed> &$init, string $logic, array<string|int, mixed> $filters) : void

Injected filters stack as siblings, and siblings combine with AND — so injectFilter() cannot express a disjunctive scope ("targeted at me OR at everyone", "mine OR public"). This does: the group is stored as a single injected entry, so prepareFilter() merges it as ONE operand and yields (a || b) && <the caller's filter>, never a || b || <the caller's filter> — which would degrade a server-side restriction into an alternative.

$this->injectFilterGroup( $init , FilterLogic::OR ,
[
    [ FilterParam::KEY => 'ownerId' , FilterParam::VAL => $userKey ] ,
    [ FilterParam::KEY => 'public'  , FilterParam::VAL => true     ] ,
]) ;
// -> FILTER ( ( doc.ownerId == @a || doc.public == true ) && <url filter> )

Operands are filter definitions (FilterParam keys) or nested groups, so an arbitrary tree can be built. An empty $filters injects nothing — a group with no operand would otherwise widen the result set to everything, which is never what a scope means.

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

The init array to enrich (passed by reference).

$logic : string

A FilterLogic operator (and / or / not).

$filters : array<string|int, mixed>

The group's operands: filter definitions, or nested groups.

injectFilters()

Injects multiple filters into the `$init` array at once — modified in place.

protected injectFilters(array<string|int, mixed> &$init, array<string|int, mixed> $filters) : void

Each filter is an array with keys from FilterParam (KEY, VAL, OP, ALT).

Example:

$this->injectFilters( $init ,
[
    [ FilterParam::KEY => 'agent'   , FilterParam::VAL => $userKey ] ,
    [ FilterParam::KEY => 'method'  , FilterParam::VAL => 'DELETE' ] ,
    [ FilterParam::KEY => 'created' , FilterParam::VAL => '2026-01-01' , FilterParam::OP => FilterComparator::GE ] ,
]) ;
Parameters
$init : array<string|int, mixed>

The init array to enrich (passed by reference).

$filters : array<string|int, mixed>

Array of filter definitions.

prepareFilter()

Overrides PrepareFilter::prepareFilter to merge URL filters with injected filters.

protected prepareFilter(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ]) : array<string|int, mixed>|null

URL filters are processed normally (stored in $params for URL display). Injected filters are appended transparently (NOT stored in $params).

The URL filter always enters the merge as a SINGLE operand of an explicit and group, never spliced into it. A filter carries three shapes — a single filter ({key,op,val}), a plain list (an implicit and), and a logic group (['or', …]) — and splicing a group would leave its operator in head position, absorbing the injected filters into the caller's own logic: a server-side restriction would silently degrade into an alternative (a || b || scope instead of (a || b) && scope), which is a scope bypass on every surface that injects a permission scope. Wrapping is shape-agnostic — the filter parser recurses, so the URL filter is resolved whole, in its own parentheses, and never meets the injected ones.

Parameters
$request : ServerRequestInterface|null

The PSR-7 request.

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

The init/args array (may contain INJECTED_FILTERS).

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

Reference to params array for URL generation.

Return values
array<string|int, mixed>|null —

The merged filter array or null.

On this page

Search results