Oihana PHP

AlterArrayPropertyTrait uses trait:short, trait:short, trait:short

Turns a value into an array and optionally alters each of its elements.

This alteration is declared with the Alter::ARRAY type. It is the entry point of the "array" branch of a property-transformation pipeline: a semicolon-separated string is first exploded into an array, then a chain of nested alter definitions can be applied to every element in turn. This makes it possible to declare a single rule that both builds the array and normalizes its content:

Property::CATEGORY => [ Alter::ARRAY , Alter::CLEAN , Alter::JSON_PARSE ] ,

The example above splits the category string into an array, removes null/empty elements, then JSON-decodes every remaining element.

The trait composes the element-level alters it can delegate to (AlterCallablePropertyTrait, AlterFloatPropertyTrait, AlterIntPropertyTrait) and dispatches the others (Alter::CLEAN, Alter::GET, Alter::HYDRATE, Alter::NORMALIZE, Alter::NOT, Alter::JSON_PARSE) through alterArrayElements().

The $modified flag is always set to true by alterArrayProperty() because the value is unconditionally coerced to an array.

Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Methods

alterArrayElements()  : array<string|int, mixed>
Applies a chain of element-level alterations to every item of an array.
alterArrayProperty()  : array<string|int, mixed>
Transforms a value into an array and applies an optional chain of element alterations.
alterCallableProperty()  : mixed
Alters a value by invoking a user-defined callable.
alterFloatProperty()  : float|array<string|int, mixed>
Casts a value (or every element of an array) to float.
alterIntProperty()  : int|array<string|int, mixed>
Casts a value (or all elements of an array) to integer.

Methods

alterArrayElements()

Applies a chain of element-level alterations to every item of an array.

public alterArrayElements(array<string|int, mixed> $array[, array<string|int, mixed> $options = [] ][, Container|null $container = null ]) : array<string|int, mixed>

Each entry of $options is either a bare Alter::* type or an array shaped as [ type , ...params ] where the extra parameters are forwarded to the corresponding element alter. The supported types are CALL, CLEAN, FLOAT, GET, HYDRATE, NORMALIZE, NOT, INT and JSON_PARSE; any unknown type leaves the array untouched. The alterations are applied sequentially, each operating on the result of the previous one. If either the array or the option list is empty, the array is returned unchanged.

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

The array whose elements must be altered.

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

An ordered list of alter definitions, each a bare Alter::* type or an array [ type , ...params ].

$container : Container|null = null

An optional DI container, forwarded to alters that resolve services (notably Alter::GET).

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:

use oihana\models\enums\Alter;

// Trim/empty-clean then JSON-decode each element
$result = $this->alterArrayElements
(
    [ '{"a":1}' , '' , '{"b":2}' ] ,
    [ Alter::CLEAN , Alter::JSON_PARSE ]
);
// $result === [ (object) [ 'a' => 1 ] , (object) [ 'b' => 2 ] ]
Return values
array<string|int, mixed> —

The array after all element-level alterations have been applied.

alterArrayProperty()

Transforms a value into an array and applies an optional chain of element alterations.

public alterArrayProperty(mixed $value[, array<string|int, mixed> $options = [] ][, Container|null $container = null ][, bool &$modified = false ]) : array<string|int, mixed>

A non-empty string is split on the semicolon (;) separator. The resulting array (or the value itself when it is already an array) is then passed to alterArrayElements() so that each chained alter definition in $options is applied to every element. Any value that is neither a string nor an array becomes an empty array.

Parameters
$value : mixed

The value to convert. A semicolon-separated string is exploded; an array is used as-is; anything else yields [].

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

An ordered list of element-level alter definitions to apply to each item (e.g. [ Alter::CLEAN , Alter::INT ]). Each entry is either an Alter::* type or an array [ type , ...params ].

$container : Container|null = null

An optional DI container, forwarded to element alters that need service resolution (e.g. Alter::GET).

$modified : bool = false

Reference flag; always set to true because the value is coerced to an array.

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:

use oihana\models\enums\Alter;
use oihana\models\traits\alters\AlterArrayPropertyTrait;

class Product
{
    use AlterArrayPropertyTrait;
}

$product  = new Product();
$modified = false;

// Split a string and cast each element to int
$ids = $product->alterArrayProperty( '10;20;30' , [ Alter::INT ] , null , $modified );
// $ids      === [ 10 , 20 , 30 ]
// $modified === true

// Already an array, cleaned of empty entries
$tags = $product->alterArrayProperty( [ 'php' , '' , 'models' ] , [ Alter::CLEAN ] , null , $modified );
// $tags === [ 0 => 'php' , 2 => 'models' ]
Return values
array<string|int, mixed> —

The resulting array after splitting and element-level alterations.

alterCallableProperty()

Alters a value by invoking a user-defined callable.

public alterCallableProperty(mixed $value[, array<string|int, mixed> $definition = [] ][, bool &$modified = false ]) : mixed

This method allows transforming a property value using any callable (closure, function name, static method, service callback, etc.). It is typically used when an alteration rule is defined as:

[
    Alter::CALLABLE,
    $callable,
    ...$additionalParams
]

The first element of $definition must be a callable or a string resolvable to a callable via resolveCallable().

The callable will be invoked with the following signature:

function (mixed $value, mixed ...$additionalParams): mixed

Any additional elements from $definition will be forwarded as extra arguments. If the callable returns a different value, $modified will be set to true.

Parameters
$value : mixed

The current value of the property to be altered.

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

The alteration definition:

  • index 0: the callable (closure, function name, or resolvable string)
  • index 1+: optional parameters passed to the callable
$modified : bool = false

Output flag set to true if the callable altered the value.

Tags
throws
InvalidArgumentException

If the callable is a string but cannot be resolved.

example 
$definition = [
    fn($value, $factor) => $value * $factor,
    2
];

$value = 10;
$value = $this->alterCallableProperty($value, $definition, $modified);

// $value    = 20
// $modified = true
Return values
mixed —

The altered value returned by the callable, or the original value if no callable was provided or callable resolution failed.

alterFloatProperty()

Casts a value (or every element of an array) to float.

public alterFloatProperty(mixed $value[, bool &$modified = false ]) : float|array<string|int, mixed>

This method ensures that the resulting value is always of type float (or an array of floats). It also sets $modified to true when any transformation occurs.

Rules:

  • If $value is already a float → returned as is, not marked modified.
  • If $value is an array → each element converted via floatval().
  • Otherwise → $value is cast to float.
Parameters
$value : mixed

The value to convert. Can be scalar or array.

$modified : bool = false

Output flag set to true if a cast was performed.

Tags
example 
$value = '12.5';
$new   = $this->alterFloatProperty($value, $modified);

// $new      = 12.5
// $modified = true

Array usage

$value = ['1.2', '3.4', 5];
$new   = $this->alterFloatProperty($value, $modified);

// $new      = [1.2, 3.4, 5.0]
// $modified = true
Return values
float|array<string|int, mixed> —

The float-cast value or an array of float-cast values.

alterIntProperty()

Casts a value (or all elements of an array) to integer.

public alterIntProperty(mixed $value[, bool &$modified = false ]) : int|array<string|int, mixed>

This alteration is typically used within property transformation pipelines to ensure that the resulting value is strictly of type int.

Behavior:

  • If $value is an array, each element is individually cast using intval().
  • If $value is already an integer, it is returned unchanged and $modified remains false.
  • If $value is not an integer, it is cast to integer and $modified becomes true.

The $modified flag will be set to true whenever at least one casting occurs (i.e., when the original value or any array element was not already an integer).

Example:

use oihana\models\traits\alters\AlterIntPropertyTrait;

class Product {
    use AlterIntPropertyTrait;
}

$product  = new Product();
$modified = false;

// Casting a single value
$id = $product->alterIntProperty("42", $modified);
// $id === 42
// $modified === true

// Casting an array of values
$values = $product->alterIntProperty(["10", "20", "30"], $modified);
// $values === [10, 20, 30]
// $modified === true

// Already an int
$count = $product->alterIntProperty(5, $modified);
// $count === 5
// $modified === false
Parameters
$value : mixed

The input value, scalar or array.

$modified : bool = false

Reference flag indicating if any cast occurred.

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

The cast integer or array of integers.

On this page

Search results