Oihana PHP

AlterBindVarsTrait uses trait:short, \oihana\traits\ContainerTrait

Applies defined alterations to a bind variables array definition based on the configured `$bindAlters`.

This method transforms the input $bindVars according to the alteration rules:

  • If $bindVars is a sequential array (list of associative arrays), alterations are recursively applied to each element.
  • If $bindVars is an associative array, only the keys defined in the selected $alters context are processed.
  • Scalar values (string, int, float, bool, resource, null) are returned unchanged unless specifically targeted in $bindAlters.
  • Supports chained alterations: if a key in $alters maps to an array of alters, each is applied in sequence, with the output of one becoming the input for the next.

The optional $context parameter allows selecting a specific subset of alterations defined under that context in $this->bindAlters. If $context is null, the top-level alterations array is used.

Example usage:

class BindVarsProcessor
{
    use AlterBindVarsTrait;

    public function __construct()
    {
        $this->bindsAlters =
        [
            'get' =>
            [
               'id' => Alter::FLOAT,
            ]
        ];
    }
}

Supported alteration types (see enum Alter):

  • Alter::ARRAY → Split string into array and apply sub-alters.
  • Alter::CLEAN → Remove empty/null elements from an array.
  • Alter::CALL → Call a function on the value.
  • Alter::FLOAT → Convert to float (or array of floats).
  • Alter::GET → Fetch a document using a model.
  • Alter::HYDRATE → Hydrate a value with a specific class.
  • Alter::INT → Convert to integer (or array of integers).
  • Alter::JSON_PARSE → Parse JSON string.
  • Alter::JSON_STRINGIFY → Convert value to JSON string.
  • Alter::MAP → Map a property of a document (or all the document structure) - Can transform or update the document.
  • Alter::NORMALIZE → Normalize a document property using configurable flags.
  • Alter::NOT → Invert boolean values.
  • Alter::URL → Generate a URL from a property.
  • Alter::VALUE → Override with a fixed value.

Mix this trait into a model (typically a PDO-backed one) when you want the bind variables passed to a prepared statement to be normalized/cast before execution — for example casting incoming string identifiers to int, prices to float, or hydrating nested documents. The alteration rules are declared once in $bindAlters and may be scoped per context.

Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Properties

$bindAlters  : array<string|int, mixed>
The alteration definitions applied to bind variables.

Methods

alterBindVars()  : array<string|int, mixed>|null
Applies defined alterations to a bind variables array definition based on the configured `$bindAlters`.
initializeBindVarsAlters()  : static
Initializes the `$bindAlters` property from an initialization array.
alterProperty()  : array<string|int, mixed>|object
Alters a specific property of the given document using one or more transformation rules.
applyChainedAlterations()  : array<string|int, mixed>|object
Applies chained alterations to a property.
applySingleAlteration()  : array<string|int, mixed>|object
Applies a single alteration (original behavior).
executeAlteration()  : mixed
Executes a specific alteration.
firstIsAlter()  : bool
Checks if a value is an Alter enum or an array starting with an Alter enum.
isChainedDefinition()  : bool
Detects if the definition represents chained alterations.

Properties

$bindAlters

The alteration definitions applied to bind variables.

public array<string|int, mixed> $bindAlters = []

Keys are either property names mapping to an Alter definition, or context names mapping to a nested array of per-property definitions (selected through the $context argument of alterBindVars()).

Methods

alterBindVars()

Applies defined alterations to a bind variables array definition based on the configured `$bindAlters`.

public alterBindVars(array<string|int, mixed>|null $bindVars[, string|null $context = null ][, int $flags = CleanFlag::DEFAULT ]) : array<string|int, mixed>|null

This method transforms the input $bindVars according to the alteration rules:

  • If $bindVars is a sequential array (list of associative arrays), alterations are recursively applied to each element.
  • If $bindVars is an associative array, only the keys defined in the selected $alters context are processed.
  • Scalar values (string, int, float, bool, resource, null) are returned unchanged unless specifically targeted in $bindAlters.
  • Supports chained alterations: if a key in $alters maps to an array of alters, each is applied in sequence, with the output of one becoming the input for the next.

The optional $context parameter allows selecting a specific subset of alterations defined under that context in $this->bindAlters. If $context is null, the top-level alterations array is used.

Parameters
$bindVars : array<string|int, mixed>|null

The bind variables definition to transform. Should be an associative array or a list of associative arrays.

$context : string|null = null

Optional context key to select a specific set of alterations from $this->bindAlters.

$flags : int = CleanFlag::DEFAULT

$flags A bitmask of CleanFlag values. Defaults to CleanFlag::DEFAULT.

Tags
throws
ContainerExceptionInterface

If an error occurs while retrieving an entry from the dependency-injection container.

DependencyException

If the dependency cannot be resolved by the container.

NotFoundException

If no entry is found for the given identifier in the container.

NotFoundExceptionInterface

If no entry is found for the requested identifier in the container.

ReflectionException

If a class or property cannot be reflected (e.g. during hydration).

example 
class BindVarsProcessor
{
use AlterBindVarsTrait;

    public function __construct()
    {
        $this->bindAlters =
        [
            'get' => [
                'id'    => Alter::INT,
                'price' => Alter::FLOAT,
            ],
        ];
   }
}

$processor = new BindVarsProcessor();
$bindVars  = ['id' => '42', 'price' => '19.99'];
$result    = $processor->alterBindVars($bindVars, 'get');

// $result:
// [
//     'id'    => 42,
//     'price' => 19.99,
// ]
Return values
array<string|int, mixed>|null —

The transformed bind variables array, preserving the input structure. Returns the original input if no alterations apply.

initializeBindVarsAlters()

Initializes the `$bindAlters` property from an initialization array.

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

The value is read from the ModelParam::BINDS_ALTERS key when present; otherwise the current value of $bindAlters is kept.

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

Initialization options, typically the model constructor payload.

Return values
static —

The current instance, for fluent chaining.

alterProperty()

Alters a specific property of the given document using one or more transformation rules.

protected alterProperty(string $key, array<string|int, mixed>|object $document, string|array<string|int, mixed> $definition[, Container|null $container = null ]) : array<string|int, mixed>|object

The transformation is defined by the $definition argument, which can be:

  • A string representing a single Alter:: constant (e.g. Alter::FLOAT)
  • An array with a single alteration and parameters: [ Alter::URL , '/product/' ]
  • An array with chained alterations (NEW): [ Alter::NORMALIZE , [ Alter::HYDRATE , Class::class ] ]
  • An array with multiple simple alterations (NEW): [ Alter::TRIM , Alter::UPPERCASE , Alter::NORMALIZE ]

If the alteration modifies the value, the altered value is set back into the document. Otherwise, the original document is returned unmodified.

Supported alter types:

  • Alter::ARRAY — Explodes a string into an array (using ;) and applies sub-alters
  • Alter::CALL — Calls a user-defined callable on the value
  • Alter::CLEAN — Removes empty ("") or null elements from arrays
  • Alter::FLOAT — Casts the value to float
  • Alter::GET — Resolves a document by ID using a model
  • Alter::HYDRATE — Hydrate a value with a specific class.
  • Alter::INT — Casts the value to integer
  • Alter::JSON_PARSE — Parses a JSON string into a PHP value
  • Alter::JSON_STRINGIFY — Encodes a value into a JSON string
  • Alter::MAP — Normalize a document property using configurable flags
  • Alter::NORMALIZE — Normalize a document property using configurable flags
  • Alter::NOT — Invert boolean values
  • Alter::URL — Generates a URL based on document properties
  • Alter::VALUE — Replaces the value with a fixed constant
Parameters
$key : string

The name of the property to alter (e.g. 'price', 'tags')

$document : array<string|int, mixed>|object

The document (array or object) passed by reference

$definition : string|array<string|int, mixed>

The alteration definition: either a string (Alter::) or an array ([ Alter::X , ...args ])

$container : Container|null = null

An optional DI container reference.

Tags
throws
ContainerExceptionInterface

If an error occurs while retrieving an entry from the dependency-injection container.

DependencyException

If the dependency cannot be resolved by the container.

NotFoundException

If no entry is found for the given identifier in the container.

NotFoundExceptionInterface

If no entry is found for the requested identifier in the container.

ReflectionException

If a class or property cannot be reflected (e.g. during hydration).

example 
$this->alters =
[
    'price'    => Alter::FLOAT,                         // Casts 'price' to float
    'tags'     => [ Alter::ARRAY , Alter::CLEAN ],      // Splits and cleans 'tags'
    'meta'     => [ Alter::JSON_PARSE ],                // Parses 'meta' JSON string
    'url'      => [ Alter::URL , '/product/' ],         // Generates a product URL
    'discount' => [ Alter::CALL , fn($v) => $v * 0.9 ], // Applies a callable
    'rating'   => [ Alter::VALUE , 5 ],                 // Fixed value replacement
    'geo'      => [ Alter::NORMALIZE , [ Alter::HYDRATE , GeoCoordinates::class ] ],
    'name'     => [ Alter::TRIM , Alter::UPPERCASE , Alter::NORMALIZE ],
];

$document =
[
    'price'    => '29.90',
    'tags'     => 'a;;b;',
    'meta'     => '{"active":true}',
    'url'      => '123',
    'discount' => 100,
    'rating'   => 0,
    'geo'      => ['latitude' => null, 'longitude' => 2.5],
    'name'     => '  john doe  ',
];

$result = $this->alterProperty('price', $document, Alter::FLOAT);
// Returns the document with 'price' casted to float (29.9)
Return values
array<string|int, mixed>|object —

The altered document (same reference type as input)

applyChainedAlterations()

Applies chained alterations to a property.

protected applyChainedAlterations(string $key, array<string|int, mixed>|object $document, array<string|int, mixed> $definitions[, Container|null $container = null ]) : array<string|int, mixed>|object

Each alteration in the chain is applied sequentially, with the output of one becoming the input of the next.

Parameters
$key : string

The property key

$document : array<string|int, mixed>|object

The document containing the property

$definitions : array<string|int, mixed>

The array of alteration definitions

$container : Container|null = null

An optional DI container reference.

Tags
throws
ContainerExceptionInterface

If an error occurs while retrieving an entry from the dependency-injection container.

DependencyException

If the dependency cannot be resolved by the container.

NotFoundException

If no entry is found for the given identifier in the container.

NotFoundExceptionInterface

If no entry is found for the requested identifier in the container.

ReflectionException

If a class or property cannot be reflected (e.g. during hydration).

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

$document The document with the altered property

applySingleAlteration()

Applies a single alteration (original behavior).

protected applySingleAlteration(string $key, array<string|int, mixed>|object $document, array<string|int, mixed> $definitions[, Container|null $container = null ]) : array<string|int, mixed>|object
Parameters
$key : string

The property key

$document : array<string|int, mixed>|object

The document containing the property

$definitions : array<string|int, mixed>

The alteration definition with parameters

$container : Container|null = null

An optional DI container reference.

Tags
throws
ContainerExceptionInterface

If an error occurs while retrieving an entry from the dependency-injection container.

DependencyException

If the dependency cannot be resolved by the container.

NotFoundException

If no entry is found for the given identifier in the container.

NotFoundExceptionInterface

If no entry is found for the requested identifier in the container.

ReflectionException

If a class or property cannot be reflected (e.g. during hydration).

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

The document with the altered property

executeAlteration()

Executes a specific alteration.

protected executeAlteration(string|Alter $alter, string $key, mixed $value, array<string|int, mixed> $params, array<string|int, mixed>|object &$document[, Container|null $container = null ][, bool &$modified = false ]) : mixed
Parameters
$alter : string|Alter

The alteration type

$key : string

The property key (for context)

$value : mixed

The value to alter

$params : array<string|int, mixed>

The alteration parameters

$document : array<string|int, mixed>|object

The full document (for context)

$container : Container|null = null

An optional DI container reference.

$modified : bool = false

Output parameter indicating if the value was modified

Tags
throws
ContainerExceptionInterface

If an error occurs while retrieving an entry from the dependency-injection container.

DependencyException

If the dependency cannot be resolved by the container.

NotFoundException

If no entry is found for the given identifier in the container.

NotFoundExceptionInterface

If no entry is found for the requested identifier in the container.

ReflectionException

If a class or property cannot be reflected (e.g. during hydration).

Return values
mixed —

The altered value

firstIsAlter()

Checks if a value is an Alter enum or an array starting with an Alter enum.

protected firstIsAlter(mixed $first) : bool
Parameters
$first : mixed

The value to check

Return values
bool —

True if it's an Alter or array with Alter as first element

isChainedDefinition()

Detects if the definition represents chained alterations.

protected isChainedDefinition(array<string|int, mixed> $definitions) : bool

Chaining is detected when:

  • The first element is an Alter enum
  • AND the second element is either:
    • Another Alter enum (simple chaining)
    • An array whose first element is an Alter enum (chaining with params)
Parameters
$definitions : array<string|int, mixed>

The alteration definitions

Return values
bool —

True if chaining is detected, false otherwise

On this page

Search results