ArrayPropertyControllerTrait
Element-level operations on an **embedded array property** of a document, exposed by {@see ArrayPropertyController} as REST sub-resources.
The host controller must be a PropertyController
subclass (it relies on its wiring: $model, $property, $owner, assertProperty(),
checkOwnerArguments(), success(), fail()). The targeted $property must be a
field declared in the model's AQL::ARRAYS option.
Each method maps an HTTP verb to a model array operation and returns a standardized response. Common error responses (built by every method through runArrayOp()):
- 400 Bad Request — the configured property is not a declared array field.
- 404 Not Found — the owner document does not exist (or, for hasItem(), the value is not present in the array).
- 422 Unprocessable Entity — moveItem() on a
sortedSetfield.
The element value is resolved from the {value} route placeholder when present,
otherwise from the request body (key value) — use the body for complex (object)
values that cannot travel in a URL.
Tags
Table of Contents
Methods
- addItem() : mixed
- Adds one or several values to the array property of a document.
- hasItem() : mixed
- Tests whether the array property of a document contains a value.
- moveItem() : mixed
- Moves an existing value to a given position in the array property.
- removeItem() : mixed
- Removes one or several values from the array property of a document.
- bodyParam() : mixed
- Reads a single parameter from the parsed request body.
- resolveItemValue() : mixed
- Resolves the array element value from the `{value}` route placeholder, falling back to the request body (key `value`) for complex values that cannot be in a URL.
- runArrayOp() : mixed
- Shared skeleton for the array operations: asserts the property is configured and declared as an array field, optionally verifies the owner document exists, then runs the given operation. Maps thrown exceptions to a standardized failure response.
Methods
addItem()
Adds one or several values to the array property of a document.
public
addItem([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed
POST /{collection}/{id}/{property} — the value(s) are read from the request
body (key value); an optional side (left/right) controls the insertion end.
Parameters
- $request : ServerRequestInterface|null = null
- $response : ResponseInterface|null = null
- $args : array<string|int, mixed> = []
-
Route placeholders (
id). - $init : array<string|int, mixed> = []
-
Optional initialization options.
Tags
Return values
mixed —The updated array property on success (200), or an error response (400/404).
hasItem()
Tests whether the array property of a document contains a value.
public
hasItem([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed
GET /{collection}/{id}/{property}/{value} — the value is read from the {value}
placeholder (or the request body for complex values).
Parameters
- $request : ServerRequestInterface|null = null
- $response : ResponseInterface|null = null
- $args : array<string|int, mixed> = []
-
Route placeholders (
id,value). - $init : array<string|int, mixed> = []
-
Optional initialization options.
Tags
Return values
mixed —200 when the value is present, 404 when it is absent (or 400/404 on guard failures).
moveItem()
Moves an existing value to a given position in the array property.
public
moveItem([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed
PATCH /{collection}/{id}/{property}/{value} — the value comes from the {value}
placeholder (or body), the target index from the request body (key position).
Unsupported on a sortedSet property (the sort order overrides positions) → 422.
Parameters
- $request : ServerRequestInterface|null = null
- $response : ResponseInterface|null = null
- $args : array<string|int, mixed> = []
-
Route placeholders (
id,value). - $init : array<string|int, mixed> = []
-
Optional initialization options.
Tags
Return values
mixed —The updated array property on success (200), or an error response (400/404/422).
removeItem()
Removes one or several values from the array property of a document.
public
removeItem([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed
DELETE /{collection}/{id}/{property}/{value} — the value comes from the {value}
placeholder (or the request body for complex values).
Parameters
- $request : ServerRequestInterface|null = null
- $response : ResponseInterface|null = null
- $args : array<string|int, mixed> = []
-
Route placeholders (
id,value). - $init : array<string|int, mixed> = []
-
Optional initialization options.
Tags
Return values
mixed —The updated array property on success (200), or an error response (400/404).
bodyParam()
Reads a single parameter from the parsed request body.
protected
bodyParam(ServerRequestInterface|null $request, string $key) : mixed
Parameters
- $request : ServerRequestInterface|null
- $key : string
Return values
mixed —The body value, or null when absent.
resolveItemValue()
Resolves the array element value from the `{value}` route placeholder, falling back to the request body (key `value`) for complex values that cannot be in a URL.
protected
resolveItemValue(ServerRequestInterface|null $request, array<string|int, mixed> $args) : mixed
Parameters
- $request : ServerRequestInterface|null
- $args : array<string|int, mixed>
runArrayOp()
Shared skeleton for the array operations: asserts the property is configured and declared as an array field, optionally verifies the owner document exists, then runs the given operation. Maps thrown exceptions to a standardized failure response.
private
runArrayOp(ServerRequestInterface|null $request, ResponseInterface|null $response, array<string|int, mixed> $args, array<string|int, mixed> $init, callable $operation[, bool $requireExists = true ]) : mixed
Parameters
- $request : ServerRequestInterface|null
- $response : ResponseInterface|null
- $args : array<string|int, mixed>
- $init : array<string|int, mixed>
- $operation : callable
-
fn(mixed $owner, Documents $model): mixed — performs the model call and returns the response.
- $requireExists : bool = true
-
When true (writes), a missing owner document yields a 404; reads (hasItem) pass false.