Oihana PHP

PrepareParamTrait uses trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short

Aggregates all the individual parameter preparation traits into a single one.

Using this trait gives a controller every prepare* helper at once (active, bench, date, filter, facets, groupBy, hasTotal, ids, interval, int, lang, limit, margin, mock, order, quantity, search, skin, sort and timezone), so request parameters can be normalized and validated in a consistent way.

Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Properties

$hasTotal  : bool
Indicates if the list method return the total number of elements.
$ids  : null|string|array<string|int, mixed>
The default ids representation, a string list with comma separator or an array.
$skinDefault  : string|null
The default skin for the controller.
$skinMethods  : array<string, string>|null
Method-specific skin definitions.
$skins  : array<string|int, string>|null
List of all available skins for the controller.

Methods

initializeHasTotal()  : static
Initialize the hasTotal property with an associative array definition.
prepareHasTotal()  : bool
Prepare and returns the 'hasTotal' value.
initializeIDs()  : void
Initialize all skins properties with an associative array definition.
initializeSkins()  : static
Initialize the skin-related properties from an associative array.
isValidSkin()  : bool
Validate a given skin.
prepareActive()  : bool|null
Prepares and returns the `active` flag.
prepareBench()  : bool
Prepares and returns the `bench` value.
prepareDate()  : string|null
Prepares and returns a date string.
preparedIDs()  : string|null
Prepares the identifier list representation (by default ids).
prepareFacets()  : array<string|int, mixed>|null
Prepares and returns the facet definitions.
prepareFilter()  : array<string|int, mixed>|null
Prepares and returns the `filter` parameter.
prepareGroupBy()  : void
Prepares the `groupBy` parameter from the request.
prepareInt()  : int|null
Prepares and returns an integer value for the given parameter name.
prepareInterval()  : void
Prepares the `interval` parameter from the request.
prepareLang()  : string|null
Prepares and returns the `lang` value.
prepareLimit()  : int
Prepare and returns the 'limit' value.
prepareMargin()  : bool|null
Prepare and returns the 'margin' flag value.
prepareMock()  : bool|null
Prepare and returns the 'mock' value.
prepareOffset()  : int
Prepare and returns the 'offset' value.
prepareOrder()  : void
Prepares the `order` direction from the request.
prepareParamsFacets()  : void
Try to creates the facets definition with the $this->params array definition of the controller.
prepareQuantity()  : int|null
Prepares and returns the `quantity` value.
prepareSearch()  : string|null
Prepares and returns the `search` value.
prepareSkin()  : string|null
Prepare and determine the effective skin for a request or method.
prepareSort()  : string|null
Prepares the sorting parameter based on the given request and arguments.
prepareTimezone()  : void
Prepare the timezone component.

Properties

$hasTotal

Indicates if the list method return the total number of elements.

public bool $hasTotal = true

$ids

The default ids representation, a string list with comma separator or an array.

public null|string|array<string|int, mixed> $ids = null

$skinDefault

The default skin for the controller.

public string|null $skinDefault = null

This skin is used when no specific skin is requested or defined.

$skinMethods

Method-specific skin definitions.

public array<string, string>|null $skinMethods = null

Array format: [ 'methodName' => 'skinName', ... ] Overrides the default skin for specific controller methods.

$skins

List of all available skins for the controller.

public array<string|int, string>|null $skins = null

Used to validate requested skins.

Methods

initializeHasTotal()

Initialize the hasTotal property with an associative array definition.

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

The configuration array, optionally carrying a ControllerParam::HAS_TOTAL entry.

Return values
static —

The current instance for chaining.

prepareHasTotal()

Prepare and returns the 'hasTotal' value.

public prepareHasTotal(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ]) : bool
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial hasTotal value.

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

A reference to the parameter bag updated in place with the prepared value.

Return values
bool —

The resolved hasTotal flag.

initializeIDs()

Initialize all skins properties with an associative array definition.

protected initializeIDs([array<string|int, mixed> $init = [] ]) : void
Parameters
$init : array<string|int, mixed> = []

The configuration array, optionally carrying a ControllerParam::IDS entry.

initializeSkins()

Initialize the skin-related properties from an associative array.

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

Example:

$this->initializeSkins([
    PrepareSkin::SKIN_DEFAULT => 'default',
    PrepareSkin::SKIN_METHODS => ['edit' => 'editor'],
    PrepareSkin::SKINS        => ['default', 'editor', 'compact']
]);
Parameters
$init : array<string, mixed> = []

Associative array of skin definitions.

Return values
static —

Returns the current instance for method chaining.

isValidSkin()

Validate a given skin.

protected isValidSkin(string|null $skin) : bool

Checks if the skin is a string and exists in the defined skins list. Converts the skin name to lowercase before validation.

Parameters
$skin : string|null

Skin name to validate.

Return values
bool —

True if the skin exists in the available skins list; false otherwise.

prepareActive()

Prepares and returns the `active` flag.

protected prepareActive(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, bool $defaultValue = true ]) : bool|null

The value resolves to the ControllerParam::ACTIVE entry of $args (or $defaultValue when absent), and is forced to false only when the request carries an active query parameter equal to 0, false or FALSE.

Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial active value.

$defaultValue : bool = true

The value used when neither the arguments nor the request define the flag.

Return values
bool|null —

The resolved active flag.

prepareBench()

Prepares and returns the `bench` value.

protected prepareBench(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ]) : bool
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial bench value.

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

A reference to the parameter bag updated in place with the prepared value.

Return values
bool —

The resolved bench flag.

prepareDate()

Prepares and returns a date string.

protected prepareDate(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ][, string|null $default = null ][, string $name = Prop::DATE ]) : string|null

The value is read from $args[$name], then the $name property, then $default, and is replaced by today's date when it does not match the resolved format. A valid $name query parameter overrides the value and is stored in $params.

Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial date and a dateFormat entry.

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

A reference to the parameter bag updated in place with the prepared date.

$default : string|null = null

The fallback date used when neither the arguments nor the property provide a valid value.

$name : string = Prop::DATE

The name of the date parameter to read and store (defaults to Prop::DATE).

Return values
string|null —

The resolved, format-validated date string.

preparedIDs()

Prepares the identifier list representation (by default ids).

protected preparedIDs(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = [] ][, string|null $name = ControllerParam::IDS ]) : string|null
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial identifier list.

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

A reference to the parameter bag updated in place with the comma-separated identifiers.

$name : string|null = ControllerParam::IDS

The name of the identifier parameter to read and store (defaults to ControllerParam::IDS).

Return values
string|null —

The resolved comma-separated identifier list, or null when none is provided.

prepareFacets()

Prepares and returns the facet definitions.

protected prepareFacets(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = [] ]) : array<string|int, mixed>|null
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial set of facets.

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

A reference to the parameter bag updated in place with the URL-encoded facet payloads.

Return values
array<string|int, mixed>|null —

The merged facet definitions.

prepareFilter()

Prepares and returns the `filter` parameter.

protected prepareFilter(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ]) : array<string|int, mixed>|null
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry a fallback filter value.

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

A reference to the parameter bag updated in place with the raw JSON filter string.

Return values
array<string|int, mixed>|null —

The decoded filter definition, or the fallback argument value when no valid filter is provided.

prepareGroupBy()

Prepares the `groupBy` parameter from the request.

protected prepareGroupBy(ServerRequestInterface|null $request, array<string|int, mixed>|null &$params, string|null &$groupBy) : void
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

$params : array<string|int, mixed>|null

A reference to the parameter bag updated in place with the resolved group-by value.

$groupBy : string|null

A reference to the group-by holder assigned in place when the request provides a value.

Tags
throws
NotFoundException

If the underlying parameter resolution fails to locate a required dependency.

prepareInt()

Prepares and returns an integer value for the given parameter name.

protected prepareInt(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ][, int|null $defaultValue = null ][, string|null $name = null ]) : int|null
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial value and validation options.

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

A reference to the parameter bag updated in place with the prepared integer.

$defaultValue : int|null = null

The fallback value used when no valid integer is resolved.

$name : string|null = null

The name of the integer parameter to read and store.

Return values
int|null —

The resolved integer value, or null when none is available.

prepareInterval()

Prepares the `interval` parameter from the request.

protected prepareInterval(ServerRequestInterface|null $request, array<string|int, mixed> &$params, string|null &$interval, array<string|int, mixed>|null $timeOptions) : void
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

$params : array<string|int, mixed>

A reference to the parameter bag updated in place with the resolved interval.

$interval : string|null

A reference to the interval holder assigned in place with the validated value.

$timeOptions : array<string|int, mixed>|null

The time configuration providing the FilterOption::MAX_RANGE bound and default interval.

prepareLang()

Prepares and returns the `lang` value.

protected prepareLang(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ]) : string|null
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial lang value.

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

A reference to the parameter bag updated in place with the resolved language.

Return values
string|null —

The resolved language code, or null when language filtering is disabled.

prepareLimit()

Prepare and returns the 'limit' value.

protected prepareLimit(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ][, int $defaultValue = 0 ][, string $property = Pagination::LIMIT ]) : int
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial pagination value.

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

A reference to the parameter bag updated in place with the prepared value.

$defaultValue : int = 0

The fallback value used when no valid integer is resolved.

$property : string = Pagination::LIMIT

The pagination property to read and store (defaults to Pagination::LIMIT).

Return values
int —

The resolved, range-clamped pagination value.

prepareMargin()

Prepare and returns the 'margin' flag value.

protected prepareMargin(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ]) : bool|null
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial margin value.

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

A reference to the parameter bag updated in place with the prepared value.

Return values
bool|null —

The resolved margin flag.

prepareMock()

Prepare and returns the 'mock' value.

protected prepareMock(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ]) : bool|null
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial mock value.

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

A reference to the parameter bag updated in place with the prepared value.

Return values
bool|null —

The resolved mock flag.

prepareOffset()

Prepare and returns the 'offset' value.

protected prepareOffset(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ][, int $defaultValue = 0 ]) : int
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial offset value.

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

A reference to the parameter bag updated in place with the prepared value.

$defaultValue : int = 0

The fallback value used when no valid integer is resolved.

Return values
int —

The resolved, range-clamped offset value.

prepareOrder()

Prepares the `order` direction from the request.

protected prepareOrder(ServerRequestInterface|null $request, array<string|int, mixed>|null &$params, mixed &$order) : void
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

$params : array<string|int, mixed>|null

A reference to the parameter bag updated in place with the resolved order direction.

$order : mixed

A reference to the order holder assigned in place when the request supplies an accepted direction.

Tags
throws
NotFoundException

If the underlying parameter resolution fails to locate a required dependency.

prepareParamsFacets()

Try to creates the facets definition with the $this->params array definition of the controller.

protected prepareParamsFacets(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed> &$facets = [] ][, array<string|int, mixed>|null &$params = [] ]) : void

Target all 'facets' definitions.

Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments, optionally carrying a ControllerParam::PARAMS mapping.

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

A reference to the facet collection enriched in place from the matching query parameters.

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

A reference to the parameter bag updated in place with the URL-encoded facet payloads.

Tags
example

To list with the controller multiple things by ids, you can invoke the route url : https://myapi/products?id=[12,255,300]

1 - Initialize the facets in the model definition :

FACETS =>
[
    Prop::ID =>
    [
         Facet::TYPE       => Facet::IN ,
         Facet::EXPRESSION => [ SQL::COLUMN => $primaryKey , SQL::TABLE => $tableAlias , SQL::ALTER => StringFunction::RTRIM   ] ,
    ] ,
]

2 - Defines the paramters behavior in the controller definition :

ControllerParam::PARAMS => [ Prop::ID => ControllerParam::FACETS ]

prepareQuantity()

Prepares and returns the `quantity` value.

protected prepareQuantity(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ][, int|null $defaultValue = null ]) : int|null
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial quantity value.

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

A reference to the parameter bag updated in place with the prepared value.

$defaultValue : int|null = null

The fallback value used when no valid integer is resolved.

Return values
int|null —

The resolved quantity, or null when none is available.

prepareSearch()

Prepares and returns the `search` value.

protected prepareSearch(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ]) : string|null
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

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

The route/controller arguments that may carry an initial search value.

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

A reference to the parameter bag updated in place with the prepared search term.

Return values
string|null —

The resolved search term, or null when none is provided.

prepareSkin()

Prepare and determine the effective skin for a request or method.

protected prepareSkin(ServerRequestInterface|null $request[, array<string, mixed> $init = [] ][, array<string, mixed>|null &$params = null ][, string|null $method = null ]) : string|null

This method considers:

  • Initialization array
  • Method-specific skin overrides
  • Query parameter in the request
  • Default skin fallback
  • Validation against available skins

Example:

$skin = $this->prepareSkin($request, ['skinDefault' => 'main'], $params, 'edit');
Parameters
$request : ServerRequestInterface|null

Optional HTTP request to read query parameters from.

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

Optional initialization array.

$params : array<string, mixed>|null = null

Reference to an array where the chosen skin will be stored.

$method : string|null = null

Optional controller method name to apply method-specific skin.

Return values
string|null —

Returns the prepared skin name in lowercase, or null if invalid or "main".

prepareSort()

Prepares the sorting parameter based on the given request and arguments.

protected prepareSort(ServerRequestInterface|null $request[, array<string|int, mixed> $args = [] ][, array<string|int, mixed>|null &$params = null ][, string|null $default = null ][, string $name = ControllerParam::SORT ]) : string|null
Parameters
$request : ServerRequestInterface|null

The request object, which may contain a sorting parameter.

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

An associative array of arguments, which may include a predefined sorting value.

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

A reference to an array where the resolved sorting parameter will be stored.

$default : string|null = null

The fallback sorting expression used when neither the arguments nor the request provide one.

$name : string = ControllerParam::SORT

The name of the sort parameter to read and store (defaults to ControllerParam::SORT).

Return values
string|null —

The resolved sorting parameter or the default sorting value if none is provided.

prepareTimezone()

Prepare the timezone component.

protected prepareTimezone(ServerRequestInterface|null $request, array<string|int, mixed>|null &$params, string|null &$timezone, array<string|int, mixed>|null $timeOptions[, string $defaultValue = 'Europe/Paris' ]) : void
Parameters
$request : ServerRequestInterface|null

The incoming PSR-7 server request, or null when no request context is available.

$params : array<string|int, mixed>|null

A reference to the parameter bag updated in place with the resolved DateTimeZone.

$timezone : string|null

A reference to the timezone holder assigned in place with the built DateTimeZone.

$timeOptions : array<string|int, mixed>|null

The time configuration providing the default timezone entry.

$defaultValue : string = 'Europe/Paris'

The fallback timezone identifier used when none is supplied (defaults to Europe/Paris).

Tags
throws
Exception

If the resolved identifier is not a valid timezone accepted by DateTimeZone.

On this page

Search results