Oihana Php Arango

PropertyController extends Controller uses PayloadsTrait, PropertyControllerGetTrait, PropertyControllerPatchTrait

The Property Controller based on the Arango DB engine.

Use a Documents model to read (get) or update (patch) a property in a Document.

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.
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.
patch() : mixed: Update a part of a document in a collection with a specific identifier (by default use the _key attribute).
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.
validateI18nShape() : array<string, string>: Pre-validate the shape of i18n-typed fields in the request body.
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.

$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
     = []

__construct()

Creates a new DocumentsController instance.


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

Parameters

$container : Container: The DI Container reference.
$init : array<string|int, mixed> = []: The optional properties to passed-in to initialize the object.

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.

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.

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.

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.

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.

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).

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> = []

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).

Return values

array<string, string> —

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

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

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

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

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

PropertyController extends Controller uses PayloadsTrait, PropertyControllerGetTrait, PropertyControllerPatchTrait

Table of Contents

Properties

Methods

Properties

$payload

Tags

Methods

__construct()

Parameters

Tags

enforceI18nShape()

Parameters

Tags

Return values

generatePayload()

Parameters

Tags

Return values

get()

Parameters

Tags

initializePayload()

Parameters

Return values

patch()

Parameters

Tags

preparePayload()

Parameters

Tags

Return values

propertyPayload()

Parameters

validateI18nShape()

Parameters

Tags

Return values

alterPayload()

Parameters

extractCustomPayloadValue()

Parameters

extractEdgePayloadValue()

Parameters

Tags

Return values

extractPayloadValue()

Parameters

Tags

extractSubPayloadValue()

Parameters

Tags

Return values

isSimplePayload()

Parameters

Return values

prefixPayloadDirectChildren()

Parameters

Return values