helpers
Table of Contents
Functions
- getBodyParam() : mixed
- Retrieves a single parameter from the HTTP request body.
- getBodyParams() : array<string|int, mixed>
- Retrieves multiple parameters from the HTTP request body.
- getController() : Controller|null
- Retrieves a controller instance from a PSR-11 container if available.
- getParam() : mixed
- Retrieves a parameter from the HTTP request, supporting query string, body, or both.
- getParamArray() : array<string|int, mixed>|null
- Retrieves a parameter from the HTTP request and ensures it is an array.
- getParamBool() : bool|null
- Retrieves a parameter from the HTTP request and ensures it is a boolean.
- getParamFloat() : float|null
- Retrieves a parameter from the HTTP request and ensures it is a float number.
- getParamFloatRange() : float|null
- Retrieves a float parameter from the request and clamps it within a given range.
- getParamInt() : int|null
- Retrieves a parameter from the HTTP request and ensures it is a int number.
- getParamIntRange() : int|null
- Retrieves an integer parameter from the request and clamps it within a given range.
- getParamNumberRange() : int|float|null
- Retrieves a numeric parameter from the request and clamps it within a given range.
- getParamString() : string|null
- Retrieves a parameter from the HTTP request and ensures it is a string.
- getQueryParam() : mixed
- Retrieves a single parameter from the HTTP request query string.
- getDocumentsModel() : DocumentsModel|null
- Resolves a {@see DocumentsModel} instance from a PSR-11 container or returns a default.
- getModel() : Model|null
- Resolves a model instance from a PSR-11 container or returns a default.
- resolveDependency() : mixed
- Resolves a dependency definition from a PSR-11 container or returns a default value.
Functions
getBodyParam()
Retrieves a single parameter from the HTTP request body.
getBodyParam(ServerRequestInterface|null $request, string $name) : mixed
This helper extracts a value from the parsed request body ($request->getParsedBody()),
supporting dot notation for nested structures (e.g. 'user.address.city').
The body is internally normalized into a fully associative array using toAssociativeArray(), ensuring compatibility with both array and stdClass-based JSON payloads.
It internally uses hasKeyValue() and getKeyValue() from the oihana\core\accessors namespace.
If the request is null, or if the specified parameter does not exist, the function returns null.
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance.
- $name : string
-
The parameter name or nested key path (e.g.
'geo.latitude').
Tags
Return values
mixed —The parameter value if found, or null otherwise.
getBodyParams()
Retrieves multiple parameters from the HTTP request body.
getBodyParams(ServerRequestInterface|null $request[, array<string|int, mixed> $names = [] ]) : array<string|int, mixed>
This helper extracts one or more values from the parsed request body ($request->getParsedBody()),
supporting dot notation for nested structures (e.g. 'user.address.city').
Each requested key from $names is resolved recursively via
hasKeyValue() and getKeyValue(), and reassembled into a new associative
array using setKeyValue(). The request body is first normalized into a pure associative
array using toAssociativeArray(), ensuring compatibility with both array and stdClass payloads.
If the request is null, the function returns null.
If none of the requested keys exist, an empty array is returned.
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance. If
null, no extraction is performed. - $names : array<string|int, mixed> = []
-
A list of parameter names (keys or dot-notated paths) to extract.
Tags
Return values
array<string|int, mixed> —An associative array of extracted values. Nested keys are preserved according to dot notation.
getController()
Retrieves a controller instance from a PSR-11 container if available.
getController([array<string|int, mixed>|string|null|Controller $definition = null ][, ContainerInterface|null $container = null ][, Controller|null $default = null ]) : Controller|null
This function attempts to fetch a controller by its identifier ($id) from the given container.
If the container is provided and contains the specified entry, it is resolved and returned
if it is an instance of Controller. Otherwise, the optional $default controller is returned.
Parameters
- $definition : array<string|int, mixed>|string|null|Controller = null
-
The controller definition within the container.
- $container : ContainerInterface|null = null
-
The PSR-11 container to fetch the controller from (optional).
- $default : Controller|null = null
-
A fallback controller to return if the container does not provide one (optional).
Tags
Return values
Controller|null —The resolved controller instance or the provided default value, or null if none found.
getParam()
Retrieves a parameter from the HTTP request, supporting query string, body, or both.
getParam(ServerRequestInterface|null $request, string $name[, array<string|int, mixed> $default = [] ][, string $strategy = HttpParamStrategy::BOTH ][, bool $throwable = false ]) : mixed
This helper searches for the requested parameter $name in the request according to the
specified $strategy:
HttpParamStrategy::QUERY→ only query string parameters.HttpParamStrategy::BODY→ only parsed body parameters.HttpParamStrategy::BOTH→ query string first, then body.
Nested keys are supported via dot notation (e.g., 'user.profile.email').
Body parameters are normalized to an associative array using toAssociativeArray().
If the parameter is not found:
- Returns the corresponding value in
$default[$name]if present. - Returns
nullif no default is provided. - Throws
DI\NotFoundExceptionif$throwableis true.
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance.
- $name : string
-
The parameter name or dot-notated path.
- $default : array<string|int, mixed> = []
-
Optional default values as an associative array.
- $strategy : string = HttpParamStrategy::BOTH
-
One of
HttpParamStrategy::QUERY|BODY|BOTH. Default: BOTH. - $throwable : bool = false
-
Whether to throw a
NotFoundExceptionif parameter is missing. Default: false.
Tags
Return values
mixed —The parameter value if found, otherwise the default value or null.
getParamArray()
Retrieves a parameter from the HTTP request and ensures it is an array.
getParamArray(ServerRequestInterface|null $request, string $name[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null $defaultValue = null ][, string $strategy = HttpParamStrategy::BOTH ][, bool $throwable = false ]) : array<string|int, mixed>|null
This helper calls getParam() and checks the returned value:
- If the value is an array, it is returned.
- Otherwise, the
$defaultValueis returned. - If
$throwableis true, aNotFoundExceptionmay be thrown bygetParam().
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance.
- $name : string
-
The parameter name or dot-notated path.
- $args : array<string|int, mixed> = []
-
Optional default values passed to
getParam(). - $defaultValue : array<string|int, mixed>|null = null
-
Value returned if the parameter is missing or not an array. Default is null.
- $strategy : string = HttpParamStrategy::BOTH
-
Which source to search:
HttpParamStrategy::BOTH|QUERY|BODY. Default is BOTH. - $throwable : bool = false
-
Whether to throw a
NotFoundExceptionif parameter is missing. Default false.
Tags
Return values
array<string|int, mixed>|null —The parameter value if it is an array, otherwise $defaultValue or null.
getParamBool()
Retrieves a parameter from the HTTP request and ensures it is a boolean.
getParamBool(ServerRequestInterface|null $request, string $name[, array<string|int, mixed> $args = [] ][, bool|null $defaultValue = null ][, string $strategy = HttpParamStrategy::BOTH ][, bool $throwable = false ]) : bool|null
This helper calls getParam() and interprets the value according to Boolean::TRUE and Boolean::FALSE:
- If the value matches
Boolean::TRUEorBoolean::FALSE, it is converted to a PHP boolean. - Otherwise, the
$defaultValueis returned. - If
$throwableis true, a NotFoundException may be thrown bygetParam().
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance.
- $name : string
-
The parameter name or dot-notated path.
- $args : array<string|int, mixed> = []
-
Optional default values passed to
getParam(). - $defaultValue : bool|null = null
-
Value returned if the parameter is missing or not a boolean. Default is null.
- $strategy : string = HttpParamStrategy::BOTH
-
Which source to search:
HttpParamStrategy::BOTH|QUERY|BODY. Default is BOTH. - $throwable : bool = false
-
Whether to throw a
NotFoundExceptionif parameter is missing. Default false.
Tags
Return values
bool|null —The parameter value if it is a boolean, otherwise $defaultValue or null.
getParamFloat()
Retrieves a parameter from the HTTP request and ensures it is a float number.
getParamFloat(ServerRequestInterface|null $request, string $name[, array<string|int, mixed> $args = [] ][, float|null $defaultValue = null ][, string $strategy = HttpParamStrategy::BOTH ][, bool $throwable = false ]) : float|null
This helper calls getParam() and converts the returned value to a float if set.
- If the value is
nullor missing, the$defaultValueis returned. - If
$throwableis true, a NotFoundException may be thrown bygetParam().
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance.
- $name : string
-
The parameter name or dot-notated path.
- $args : array<string|int, mixed> = []
-
Optional default values passed to
getParam(). - $defaultValue : float|null = null
-
Value returned if the parameter is missing or not set. Default is null.
- $strategy : string = HttpParamStrategy::BOTH
-
Which source to search:
HttpParamStrategy::BOTH|QUERY|BODY. Default is BOTH. - $throwable : bool = false
-
Whether to throw a
NotFoundExceptionif parameter is missing. Default false.
Tags
Return values
float|null —The parameter value cast to float if present, otherwise $defaultValue or null.
getParamFloatRange()
Retrieves a float parameter from the request and clamps it within a given range.
getParamFloatRange(ServerRequestInterface|null $request, string $name, float $min, float $max[, float|null $defaultValue = null ][, array<string|int, mixed> $args = [] ][, string $strategy = HttpParamStrategy::BOTH ][, bool $throwable = false ]) : float|null
Wrapper around getParamNumberRange() that ensures float return type.
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance. Can be null.
- $name : string
-
The parameter name or dot-notated path.
- $min : float
-
Minimum allowed float value.
- $max : float
-
Maximum allowed float value.
- $defaultValue : float|null = null
-
Value returned if the parameter is missing or not numeric. Default null.
- $args : array<string|int, mixed> = []
-
Optional defaults passed to getParam().
- $strategy : string = HttpParamStrategy::BOTH
-
Which source to search:
HttpParamStrategy::BOTH|QUERY|BODY. Default BOTH. - $throwable : bool = false
-
Whether to throw NotFoundException if the parameter is missing. Default false.
Tags
Return values
float|null —The float value clamped to [$min, $max], or $defaultValue/null if missing or invalid.
getParamInt()
Retrieves a parameter from the HTTP request and ensures it is a int number.
getParamInt(ServerRequestInterface|null $request, string $name[, array<string|int, mixed> $args = [] ][, int|null $defaultValue = null ][, string $strategy = HttpParamStrategy::BOTH ][, bool $throwable = false ]) : int|null
This helper calls getParam() and converts the returned value to a int if set.
- If the value is
nullor missing, the$defaultValueis returned. - If
$throwableis true, a NotFoundException may be thrown bygetParam().
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance.
- $name : string
-
The parameter name or dot-notated path.
- $args : array<string|int, mixed> = []
-
Optional default values passed to
getParam(). - $defaultValue : int|null = null
-
Value returned if the parameter is missing or not set. Default is null.
- $strategy : string = HttpParamStrategy::BOTH
-
Which source to search:
HttpParamStrategy::BOTH|QUERY|BODY. Default is BOTH. - $throwable : bool = false
-
Whether to throw a
NotFoundExceptionif parameter is missing. Default false.
Tags
Return values
int|null —The parameter value cast to int if present, otherwise $defaultValue or null.
getParamIntRange()
Retrieves an integer parameter from the request and clamps it within a given range.
getParamIntRange(ServerRequestInterface|null $request, string $name, int $min, int $max[, int|null $defaultValue = null ][, array<string|int, mixed> $args = [] ][, string $strategy = HttpParamStrategy::BOTH ][, bool $throwable = false ]) : int|null
Wrapper around getParamNumberRange() that ensures integer return type.
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance. Can be null.
- $name : string
-
The parameter name or dot-notated path.
- $min : int
-
Minimum allowed integer value.
- $max : int
-
Maximum allowed integer value.
- $defaultValue : int|null = null
-
Value returned if the parameter is missing or not numeric. Default null.
- $args : array<string|int, mixed> = []
-
Optional defaults passed to getParam().
- $strategy : string = HttpParamStrategy::BOTH
-
Which source to search:
HttpParamStrategy::BOTH|QUERY|BODY. Default BOTH. - $throwable : bool = false
-
Whether to throw NotFoundException if the parameter is missing. Default false.
Tags
Return values
int|null —The integer value clamped to [$min, $max], or $defaultValue/null if missing or invalid.
getParamNumberRange()
Retrieves a numeric parameter from the request and clamps it within a given range.
getParamNumberRange(ServerRequestInterface|null $request, string $name, int|float $min, int|float $max[, int|float|null $defaultValue = null ][, array<string|int, mixed> $args = [] ][, string $strategy = HttpParamStrategy::BOTH ][, bool $throwable = false ]) : int|float|null
This helper calls getParam() and:
- Converts the value to int or float.
- Returns
$defaultValueif the parameter is missing or not numeric. - Clamps the value between
$minand$max. - Can throw NotFoundException if
$throwableis true and parameter is missing.
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 request instance.
- $name : string
-
Parameter name or dot-notated path.
- $min : int|float
-
Minimum allowed value.
- $max : int|float
-
Maximum allowed value.
- $defaultValue : int|float|null = null
-
Value returned if missing or invalid. Default null.
- $args : array<string|int, mixed> = []
-
Optional defaults passed to getParam().
- $strategy : string = HttpParamStrategy::BOTH
-
Source to search: BOTH, QUERY, BODY. Default BOTH.
- $throwable : bool = false
-
Whether to throw NotFoundException if missing. Default false.
Tags
Return values
int|float|null —The numeric value clamped to the range [$min, $max], or $defaultValue/null if missing or invalid.
getParamString()
Retrieves a parameter from the HTTP request and ensures it is a string.
getParamString(ServerRequestInterface|null $request, string $name[, array<string|int, mixed> $args = [] ][, string|null $defaultValue = null ][, string $strategy = HttpParamStrategy::BOTH ][, bool $throwable = false ]) : string|null
This helper calls getParam() and converts the returned value to a string if set.
- If the value is
nullor missing, the$defaultValueis returned. - If
$throwableis true, a NotFoundException may be thrown bygetParam().
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance.
- $name : string
-
The parameter name or dot-notated path.
- $args : array<string|int, mixed> = []
-
Optional default values passed to
getParam(). - $defaultValue : string|null = null
-
Value returned if the parameter is missing or null. Default is null.
- $strategy : string = HttpParamStrategy::BOTH
-
Which source to search:
HttpParamStrategy::BOTH|QUERY|BODY. Default is BOTH. - $throwable : bool = false
-
Whether to throw a
NotFoundExceptionif parameter is missing. Default false.
Tags
Return values
string|null —The parameter value cast to string if present, otherwise $defaultValue or null.
getQueryParam()
Retrieves a single parameter from the HTTP request query string.
getQueryParam(ServerRequestInterface|null $request, string $name) : mixed
This helper extracts a value from the query parameters ($request->getQueryParams()),
supporting dot notation for nested structures (e.g. 'filter.page').
It internally uses hasKeyValue() and getKeyValue() from the
oihana\core\accessors namespace.
If the request is null, or if the specified parameter does not exist, the function returns null.
Parameters
- $request : ServerRequestInterface|null
-
The PSR-7 server request instance. If
null, no extraction is performed. - $name : string
-
The query parameter name or nested key path (e.g.
'filter.page').
Tags
Return values
mixed —The parameter value if found, or null otherwise.
getDocumentsModel()
Resolves a {@see DocumentsModel} instance from a PSR-11 container or returns a default.
getDocumentsModel([string|DocumentsModel|null $definition = null ][, ContainerInterface|null $container = null ][, DocumentsModel|null $default = null ]) : DocumentsModel|null
This helper function provides a flexible way to obtain a DocumentsModel instance:
- If
$definitionis already aDocumentsModel, it is returned as-is. - If
$definitionis a string and$containerimplements ContainerInterface, the function attempts to resolve the corresponding service from the container. - If resolution fails, the provided
$default(if any) is returned instead.
This pattern allows for safe dependency resolution in controllers or services, without requiring explicit type-checking or container awareness in user code.
Parameters
- $definition : string|DocumentsModel|null = null
-
The model definition — either:
- a
DocumentsModelinstance (returned directly), - a string service identifier (resolved from
$container), - or
null(uses$default).
- a
- $container : ContainerInterface|null = null
-
Optional PSR-11 container to resolve string identifiers.
- $default : DocumentsModel|null = null
-
Optional fallback model if no valid instance is found.
Tags
Return values
DocumentsModel|null —The resolved model, the provided default, or null if none.
getModel()
Resolves a model instance from a PSR-11 container or returns a default.
getModel([array<string|int, mixed>|string|Model|null $definition = null ][, ContainerInterface|null $container = null ][, Model|null $default = null ]) : Model|null
This function attempts to retrieve a Model instance based on the provided
definition. The definition can be:
- A
Modelinstance (returned directly), - An array containing a
ModelParam::MODELkey, - A string identifier for a model in a PSR-11 container.
Parameters
- $definition : array<string|int, mixed>|string|Model|null = null
-
The model definition, which can be:
- a Model instance,
- an array with key
ModelParam::MODEL, - a string identifier in the container,
- or null.
- $container : ContainerInterface|null = null
-
Optional PSR-11 container used to resolve a string definition.
- $default : Model|null = null
-
Optional fallback model returned if none could be resolved.
Tags
Return values
Model|null —The resolved Model instance, the provided default, or null if none found.
resolveDependency()
Resolves a dependency definition from a PSR-11 container or returns a default value.
resolveDependency(string|null $dependency[, ContainerInterface|null $container = null ][, mixed $default = null ]) : mixed
This function attempts to retrieve a service or object from a PSR-11 container if a string identifier is provided. If the container is null, the dependency is not found, or the input is not a string, the provided default value is returned.
Parameters
- $dependency : string|null
-
The container entry ID to resolve.
- $container : ContainerInterface|null = null
-
Optional PSR-11 container to resolve the dependency from.
- $default : mixed = null
-
Value to return if the dependency cannot be resolved.
Tags
Return values
mixed —Returns the resolved dependency from the container, or $default if not found.