Oihana PHP Arango

DocumentsController extends Controller uses AuthorizationContextTrait, DocumentsControllerCapabilitiesTrait, DocumentsControllerCountTrait, DocumentsControllerDeleteTrait, DocumentsControllerGetTrait, DocumentsControllerLastTrait, DocumentsControllerListTrait, DocumentsControllerPatchTrait, DocumentsControllerPostTrait, DocumentsControllerPutTrait, ModelCallTrait, PayloadsTrait, PermissionAuthorizerTrait

The Document Controller based on the Arango DB engine.

This controller implement the methods :

  • count()
  • delete()
  • get()
  • last()
  • list()
  • post()

Capability-aware overrides (skin gating, filter key gating, ...) are bundled in DocumentsControllerCapabilitiesTrait, opt-in through the ControllerParam::CAPABILITIES init block.

Table of Contents

Properties

$payload  : string|array<string|int, mixed>|null
The initial payload definition to prepare a new document to insert in a collection with the POST/PATCH/PUT methods.

Methods

__construct()  : mixed
Creates a new DocumentsController instance.
count()  : mixed
Returns the number of documents in the collection.
delete()  : ResponseInterface
Deletes one or more documents from the collection.
enforceI18nShape()  : ResponseInterface|null
Pre-validate the i18n-typed fields and short-circuit with a 422 if any field has an invalid shape.
generatePayload()  : array<string|int, mixed>
Prepares a key-value payload object based on the provided request and definitions.
get()  : mixed
Returns a specific document with a specific identifier.
initializePayload()  : static
Initialize the 'payload' definition used to prepare a document for insertion or replace/update.
last()  : mixed
Returns the last document modified or with a specific date property in the collection.
list()  : mixed
List a set of elements with the model.
patch()  : mixed
Update a part of a document in a collection with a specific identifier (by default use the _key attribute).
post()  : mixed
Post a new document in an Arango DB collection.
preparePayload()  : array<string|int, mixed>
Prepare the 'payload' to insert or modify in the POST, PATCH or PUT methods.
propertyPayload()  : mixed
Returns an associative array with a key/value definition based on the property name and the payload request object.
put()  : mixed
Replace a document in a collection with a specific identifier (by default use the _key attribute).
validateI18nShape()  : array<string, string>
Pre-validate the shape of i18n-typed fields in the request body.
initializeAuthorizationContext()  : static
Resolves the capability enforcer and the permission-subject resolver from the container (each guarded by an `instanceof`, null when absent) and wires them through `initializeCapabilities()` and `initializePermissionSubjectResolver()`.
alterPayload()  : mixed
Apply an alteration function to a payload value.
extractCustomPayloadValue()  : mixed
Extract a custom type value (method-based or fallback).
extractEdgePayloadValue()  : string|null
Extract a payload 'EDGE' type value and register it in relations.
extractPayloadValue()  : mixed
Extract a single payload value based on its type definition.
extractSubPayloadValue()  : array<string|int, mixed>|null
Extract a payload 'PAYLOAD' type value (recursive payload generation).
isSimplePayload()  : bool
Determine if the payload definition is a simple value (not a complex document structure).
prefixPayloadDirectChildren()  : array<string|int, mixed>
Prefix only the direct children field names with parent key.

Properties

$payload

The initial payload definition to prepare a new document to insert in a collection with the POST/PATCH/PUT methods.

public string|array<string|int, mixed>|null $payload = []
Tags
see
PayloadsTrait
example

$controller->payload = [ HttpMethod::ALL => [ Prop::NAME => AQLType::STRING , Prop::ALGORITHM => [ Arango::TYPE => AQLType::STRING , Arango::DEFAULT => JWTAlgorithm::HS256 ] , Prop::DESCRIPTION => [ Arango::TYPE => AQLType::I18N ] , Prop::ADDRESS => [ Arango::TYPE => AQLType::OBJECT , Arango::COMPRESS => true , Arango::PAYLOAD => [ Prop::STREET_ADDRESS => [ Arango::TYPE => AQLType::STRING ] , Prop::EXTENDED_ADDRESS => [ Arango::TYPE => AQLType::STRING ] , Prop::ADDRESS_LOCALITY => [ Arango::TYPE => AQLType::STRING ] , Prop::ADDRESS_COUNTRY => [ Arango::TYPE => AQLType::STRING ] , Prop::ADDRESS_DEPARTMENT => [ Arango::TYPE => AQLType::STRING ] , Prop::ADDRESS_REGION => [ Arango::TYPE => AQLType::STRING ] , Prop::POST_OFFICE_BOX_NUMBER => [ Arango::TYPE => AQLType::STRING ] , ] ] , ], HttpMethod::POST => [ Prop::IDENTIFIER => [ Arango::TYPE => AQLType::STRING ] , Prop::ACTIVE => [ Arango::VALUE => 1 ] , Prop::WITH_STATUS => [ Arango::VALUE => Status::PUBLISHED ] , Prop::ALLOW_OFFLINE_ACCESS => [ Arango::VALUE => true ] , Prop::RBAC => [ Arango::VALUE => true ] , Prop::SCOPE_HAS_PERMISSION => [ Arango::VALUE => true ] , Prop::SKIP_USER_CONSENT => [ Arango::VALUE => true ] , Prop::TOKEN_EXPIRATION => [ Arango::VALUE => 86400 ] , Prop::WEB_TOKEN_EXPIRATION => [ Arango::VALUE => 7200 ] , ], HttpMethod::PATCH => [ Prop::ALLOW_OFFLINE_ACCESS => [ Arango::TYPE => AQLType::BOOL ] , Prop::RBAC => [ Arango::TYPE => AQLType::BOOL ] , Prop::SCOPE_HAS_PERMISSION => [ Arango::TYPE => AQLType::BOOL ] , Prop::SKIP_USER_CONSENT => [ Arango::TYPE => AQLType::BOOL ] , Prop::TOKEN_EXPIRATION => [ Arango::TYPE => AQLType::INT ] , Prop::WEB_TOKEN_EXPIRATION => [ Arango::TYPE => AQLType::INT ] , ] ] ;

Methods

__construct()

Creates a new DocumentsController instance.

public __construct(Container $container[, array<string, mixed> $init = [] ]) : mixed
Parameters
$container : Container

The DI Container reference.

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

The optional properties to initialize the object.

Tags
throws
ContainerExceptionInterface
NotFoundExceptionInterface
DependencyException
NotFoundException
ReflectionException

count()

Returns the number of documents in the collection.

public count([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed
Parameters
$request : ServerRequestInterface|null = null
$response : ResponseInterface|null = null
$args : array<string|int, mixed> = []

An associative array that contains values for the current route’s named placeholders.

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

An optional associative array to initialize the method.

Tags
throws
ContainerExceptionInterface
NotFoundExceptionInterface

delete()

Deletes one or more documents from the collection.

public delete([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : ResponseInterface

This method provides a flexible endpoint for document deletion. It can handle a single document ID provided as a route placeholder or one or more IDs supplied via a query parameter.

When multiple IDs are passed in the query string, they are cleaned to remove empty values and duplicates, then sorted using a natural sort algorithm before being processed by the model. The response format adapts to return the key of a single deleted document or an array of keys for multiple deletions.

Parameters
$request : ServerRequestInterface|null = null

The PSR-7 request object, used to access query parameters.

$response : ResponseInterface|null = null

The PSR-7 response object, used to build the HTTP response.

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

An associative array of route placeholders. It is expected to contain the 'id' key for single-item deletion.

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

An optional associative array to pass custom settings to the model layer (e.g., skipping existence checks).

Tags
example 
// Delete a single document via route argument
DELETE /things/12515

// Delete a single document via query parameter
DELETE /things?id=12515

// Delete multiple documents via query parameter
DELETE /things?id=12515,241545,10
Return values
ResponseInterface —

Returns an HTTP response object indicating the result of the operation. On success, the body contains the _key of the deleted document(s). On failure, it returns a formatted error response (400, 404, or 500).

enforceI18nShape()

Pre-validate the i18n-typed fields and short-circuit with a 422 if any field has an invalid shape.

public enforceI18nShape(ServerRequestInterface|null $request, ResponseInterface|null $response[, string|null $method = null ][, array<string|int, mixed> $init = [] ]) : ResponseInterface|null

Convenience wrapper around validateI18nShape() that builds the canonical "Unprocessable Entity" response when validation fails. Callers should return the response directly when this method returns a non-null value.

Parameters
$request : ServerRequestInterface|null

The current HTTP request.

$response : ResponseInterface|null

The current HTTP response.

$method : string|null = null

The HTTP method (POST, PATCH, PUT).

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

Optional override of the payload definitions.

Tags
throws
NotFoundException
Return values
ResponseInterface|null —

Null when the body is well-formed, otherwise the 422 response to return.

generatePayload()

Prepares a key-value payload object based on the provided request and definitions.

public generatePayload(ServerRequestInterface $request[, array<string|int, mixed>|null $definitions = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> &$relations = [] ][, bool $throwable = false ]) : array<string|int, mixed>

This method processes the given definitions and extracts values from the request based on the type specified in the definitions.

If a type is not specified but a value is provided in the definitions, that value is directly assigned to the document.

Parameters
$request : ServerRequestInterface

The request object that contains the input data.

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

An array of definitions that specify the types and names of expected parameters or their predefined values. Each definition may include a type (e.g., BOOL, FLOAT, I18N, INT, etc.), a name, or a predefined value.

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

The optional arguments to initialize the document key/value.

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

The array reference to register all payload attributes with a relation behavior (edges).

$throwable : bool = false

Indicates if the method throws errors.

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

An associative array containing the processed key-value pairs extracted or derived from the request and definitions.

get()

Returns a specific document with a specific identifier.

public get([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed

Ex: ../element?search=film Ex: ../element?facets={"location":12} Ex: ../element?facets={"type":"-event,visual/exhibition","eventStatus":"-scheduled"}

Parameters
$request : ServerRequestInterface|null = null
$response : ResponseInterface|null = null
$args : array<string|int, mixed> = []

An associative array that contains values for the current route’s named placeholders.

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

An optional associative array to initialize the method.

Tags
throws
ContainerExceptionInterface
NotFoundExceptionInterface

initializePayload()

Initialize the 'payload' definition used to prepare a document for insertion or replace/update.

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

This method sets the $payload property based on the provided associative array. If the array contains the key Arango::PAYLOADS, its value will replace the current payload. Otherwise, the existing payload is kept.

Example:

$controller->initializePayloads
([
    Arango::PAYLOADS =>
    [
        HttpMethod::ALL =>
        [
            Prop::NAME => [ Arango::TYPE => AQLType::STRING ],
            Prop::ADDRESS     =>
            [
                Arango::TYPE     => AQLType::OBJECT ,
                Arango::COMPRESS => true ,
                Arango::PAYLOAD  =>
                [
                    Prop::STREET_ADDRESS         => [ Arango::TYPE => AQLType::STRING ] ,
                    Prop::EXTENDED_ADDRESS       => [ Arango::TYPE => AQLType::STRING ] ,
                    Prop::ADDRESS_LOCALITY       => [ Arango::TYPE => AQLType::STRING ] ,
                    Prop::ADDRESS_COUNTRY        => [ Arango::TYPE => AQLType::STRING ] ,
                    Prop::ADDRESS_DEPARTMENT     => [ Arango::TYPE => AQLType::STRING ] ,
                    Prop::ADDRESS_REGION         => [ Arango::TYPE => AQLType::STRING ] ,
                    Prop::POST_OFFICE_BOX_NUMBER => [ Arango::TYPE => AQLType::STRING ] ,
                ]
            ]
            // ... other field definitions
        ],
        HttpMethod::POST =>
        [
            Prop::ACTIVE => [ Arango::VALUE => 1 ],
            // ... other field definitions
        ],
    ],
]);
Parameters
$init : array<string|int, mixed> = []

Associative array containing the schema definition.

Return values
static —

Returns the current instance for method chaining.

last()

Returns the last document modified or with a specific date property in the collection.

public last([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed
Parameters
$request : ServerRequestInterface|null = null
$response : ResponseInterface|null = null
$args : array<string|int, mixed> = []

An associative array that contains values for the current route’s named placeholders.

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

An optional associative array to initialize the method.

Tags
throws
ContainerExceptionInterface
NotFoundExceptionInterface

list()

List a set of elements with the model.

public list([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed

Ex: ../element?search=film Ex: ../element?facets={"location":12} Ex: ../element?facets={"type":"-event,visual/exhibition","eventStatus":"-scheduled"}

Parameters
$request : ServerRequestInterface|null = null
$response : ResponseInterface|null = null
$args : array<string|int, mixed> = []

The route arguments

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

ex: [ 'limit' => 0 ]

Tags
throws
ContainerExceptionInterface
NotFoundExceptionInterface

patch()

Update a part of a document in a collection with a specific identifier (by default use the _key attribute).

public patch([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed

Example: PATCH ../collection/{id}

Parameters
$request : ServerRequestInterface|null = null
$response : ResponseInterface|null = null
$args : array<string|int, mixed> = []

An associative array that contains values for the current route’s named placeholders.

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

An optional associative array to initialize the method.

post()

Post a new document in an Arango DB collection.

public post([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed
Parameters
$request : ServerRequestInterface|null = null
$response : ResponseInterface|null = null
$args : array<string|int, mixed> = []

An associative array that contains values for the current route’s named placeholders.

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

An optional associative array to initialize the method.

preparePayload()

Prepare the 'payload' to insert or modify in the POST, PATCH or PUT methods.

public preparePayload(ServerRequestInterface|null $request[, string|null $method = null ][, array<string|int, mixed> $init = [] ][, array<string|int, mixed> &$relations = [] ]) : array<string|int, mixed>

This method builds a document array based on the request body and the payload definitions corresponding to the current HTTP method.

It can optionally "compress" the document structure depending on the compress configuration.

Parameters
$request : ServerRequestInterface|null

The current HTTP request instance (may be null).

$method : string|null = null

The current HTTP method (e.g. HttpMethod::POST, HttpMethod::PATCH, HttpMethod::PUT).

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

Initialization options to customize behavior:

  • compress (array|bool) Compress behavior definition (default: false).
    • If true, the document is always compressed.
    • If an array, only compress when the current method is included (e.g. [HttpMethod::POST, HttpMethod::PATCH]).
  • payload (array) Definition to override the default payload settings.
$relations : array<string|int, mixed> = []

The array reference to register all payload attributes with a relation behavior (edges).

Tags
throws
DependencyException

If a required dependency cannot be resolved.

NotFoundException

If a required payload or service is not found.

Return values
array<string|int, mixed> —

The prepared document ready for insertion or modification.

propertyPayload()

Returns an associative array with a key/value definition based on the property name and the payload request object.

public propertyPayload(ServerRequestInterface $request, mixed $property[, array<string|int, mixed> &$relations = [] ]) : mixed
Parameters
$request : ServerRequestInterface
$property : mixed
$relations : array<string|int, mixed> = []

put()

Replace a document in a collection with a specific identifier (by default use the _key attribute).

public put([ServerRequestInterface|null $request = null ][, ResponseInterface|null $response = null ][, array<string|int, mixed> $args = [] ][, array<string|int, mixed> $init = [] ]) : mixed

Example: PUT ../collection/{id}

Parameters
$request : ServerRequestInterface|null = null
$response : ResponseInterface|null = null
$args : array<string|int, mixed> = []

An associative array that contains values for the current route’s named placeholders.

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

An optional associative array to initialize the method.

validateI18nShape()

Pre-validate the shape of i18n-typed fields in the request body.

public validateI18nShape(ServerRequestInterface|null $request[, string|null $method = null ][, array<string|int, mixed> $init = [] ]) : array<string, string>

Inspects the payload definitions for fields typed as AQLType::I18N and checks the raw request body. If any such field is present with a non-array/object/null value (e.g. a flat string), an entry is returned for it. Callers should respond with a 422 when the result is non-empty, before invoking preparePayload() (which would otherwise drop the invalid value silently via filterLanguages()).

Parameters
$request : ServerRequestInterface|null

The current HTTP request.

$method : string|null = null

The HTTP method (POST, PATCH, PUT).

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

Optional override of the payload definitions (same shape as preparePayload's $init).

Tags
throws
NotFoundException
Return values
array<string, string> —

Map of field name → error message. Empty when the body is well-formed.

initializeAuthorizationContext()

Resolves the capability enforcer and the permission-subject resolver from the container (each guarded by an `instanceof`, null when absent) and wires them through `initializeCapabilities()` and `initializePermissionSubjectResolver()`.

protected initializeAuthorizationContext([array<string, mixed> $init = [] ]) : static
Parameters
$init : array<string, mixed> = []

Same array passed to the controller constructor.

Tags
throws
DependencyException
NotFoundException
Return values
static

alterPayload()

Apply an alteration function to a payload value.

private alterPayload(mixed $value, mixed $alter) : mixed
Parameters
$value : mixed
$alter : mixed

extractCustomPayloadValue()

Extract a custom type value (method-based or fallback).

private extractCustomPayloadValue(ServerRequestInterface $request, string|null $type, string $name, array<string|int, mixed> $args, array<string|int, mixed> $options, mixed $default) : mixed
Parameters
$request : ServerRequestInterface
$type : string|null
$name : string
$args : array<string|int, mixed>
$options : array<string|int, mixed>
$default : mixed

extractEdgePayloadValue()

Extract a payload 'EDGE' type value and register it in relations.

private extractEdgePayloadValue(ServerRequestInterface $request, string $name, string $key, array<string|int, mixed> $options, array<string|int, mixed> $args, array<string|int, mixed> &$relations, mixed $default, bool $throwable) : string|null
Parameters
$request : ServerRequestInterface
$name : string
$key : string
$options : array<string|int, mixed>
$args : array<string|int, mixed>
$relations : array<string|int, mixed>
$default : mixed
$throwable : bool
Tags
throws
NotFoundException
Return values
string|null

extractPayloadValue()

Extract a single payload value based on its type definition.

private extractPayloadValue(ServerRequestInterface $request, string $key, array<string|int, mixed> $options, array<string|int, mixed> $args, array<string|int, mixed> &$relations, bool $throwable) : mixed
Parameters
$request : ServerRequestInterface
$key : string
$options : array<string|int, mixed>
$args : array<string|int, mixed>
$relations : array<string|int, mixed>
$throwable : bool
Tags
throws
DependencyException
NotFoundException

extractSubPayloadValue()

Extract a payload 'PAYLOAD' type value (recursive payload generation).

private extractSubPayloadValue(ServerRequestInterface $request, string $parentKey, array<string|int, mixed> $options, array<string|int, mixed> $args, array<string|int, mixed> &$relations, bool $throwable) : array<string|int, mixed>|null

This method automatically prefixes nested field names with their parent key if no explicit Arango::NAME is provided.

The prefixing is done "just-in-time" only for direct children, not recursively. Nested PAYLOAD types will handle their own prefixing when they are processed.

Example:

  • Parent key: 'address'
  • Child key: 'postalCode'
  • Generated name: 'address.postalCode'
Parameters
$request : ServerRequestInterface
$parentKey : string

The parent key to use as prefix for nested fields

$options : array<string|int, mixed>
$args : array<string|int, mixed>
$relations : array<string|int, mixed>
$throwable : bool
Tags
throws
DependencyException
NotFoundException
Return values
array<string|int, mixed>|null

isSimplePayload()

Determine if the payload definition is a simple value (not a complex document structure).

private isSimplePayload(mixed $definition) : bool
Parameters
$definition : mixed
Return values
bool

prefixPayloadDirectChildren()

Prefix only the direct children field names with parent key.

private prefixPayloadDirectChildren(array<string|int, mixed> $definitions, string $prefix[, string $separator = '.' ]) : array<string|int, mixed>

Does NOT recursively process nested PAYLOAD types - they will be handled by their own extractSubPayloadValue call during generatePayload execution.

Automatically generates hierarchical names like 'address.postalCode' for fields that don't already have an explicit Arango::NAME.

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

The nested payload definitions

$prefix : string

The parent key to use as prefix

$separator : string = '.'

The separator between parent and child keys (default: '.')

Return values
array<string|int, mixed> —

The definitions with auto-generated names for direct children only

On this page

Search results