Oihana PHP System

AlterBindVarsTrait uses trait:short, trait:short

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.
Tags
throws
ContainerExceptionInterface
throws
NotFoundExceptionInterface
throws
DependencyException
throws
NotFoundException
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Properties

$bindAlters  : array<string|int, mixed>
The enumeration of all definitions to alter on the array or object key/value properties.
$container  : Container
The DI container reference.

Methods

alterBindVars()  : array<string|int, mixed>|null
Applies defined alterations to a bind variables array definition based on the configured `$bindAlters`.
initializeBindVarsAlters()  : static
Initialize the 'bindAlters' property.
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 enumeration of all definitions to alter on the array or object key/value properties.

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

$container

The DI container reference.

public Container $container

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 a DI container error occurs during alteration.

throws
DependencyException

If a dependency cannot be resolved during alteration.

throws
NotFoundException

If a container service is not found during alteration.

throws
NotFoundExceptionInterface

If a container service is not found during alteration.

throws
ReflectionException

If a reflection operation fails during alteration (e.g., Hydrate or Get).

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

Initialize the 'bindAlters' property.

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

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
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface
throws
ReflectionException
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
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface
throws
ReflectionException
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
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface
throws
ReflectionException
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
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface
throws
ReflectionException
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