Oihana PHP Arango

PayloadsTrait uses \oihana\controllers\traits\LanguagesTrait, \oihana\logging\LoggerTrait, \oihana\controllers\traits\ParamsStrategyTrait, \oihana\controllers\traits\PathTrait

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

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.
initializePayload()  : static
Initialize the 'payload' definition used to prepare a document for insertion or replace/update.
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.

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

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.

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.

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

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.

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