Oihana PHP System

AlterDocumentTrait uses trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short, trait:short

Provides a system to alter properties of arrays or objects based on a configurable set of rules (called "alters").

The alteration definitions are stored in the $alters array and can apply various transformations to data, such as converting values to floats, parsing JSON, cleaning arrays, or resolving URLs.

Example usage:

class MyProcessor {
use AlterDocumentTrait;

public function __construct()
{
$this->alters = [
'price'    => Alter::FLOAT,
'tags'     => [ Alter::ARRAY , Alter::CLEAN ],
'meta'     => [ Alter::JSON_PARSE ],
'link'     => [ Alter::URL , '/product/' ],
'score'    => [ Alter::CALL , fn($value) => $value * 10 ],
];
}
}

$processor = new MyProcessor();
$data = [
'price' => '12.5',
'tags'  => 'tag1;;tag2;',
'meta'  => '{"views":100}',
'link'  => '123',
'score' => 7,
];

$processed = $processor->alter($data);
// Result:
// [
//     'price' => 12.5,
//     'tags'  => ['tag1', 'tag2'],
//     'meta'  => ['views' => 100],
//     'link'  => '/product/123',
//     'score' => 70,
// ]

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::INT → Convert to integer (or array of integers).
  • Alter::JSON_PARSE → Parse JSON string.
  • Alter::JSON_STRINGIFY → Convert value to JSON string.
  • 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

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

Methods

alter()  : mixed
Alters the given document (array or object) based on the configured `$alters` definitions.
alterArrayCleanProperty()  : array<string|int, mixed>|float
Clean an array of null or empty string elements.
alterArrayElements()  : array<string|int, mixed>
Alters all elements in an array.
alterArrayProperty()  : array<string|int, mixed>
Transform a string expression separated by semi-colon ';' to creates an array.
alterAssociativeArray()  : array<string|int, mixed>
Alter the passed-in array.
alterCallableProperty()  : mixed
Call a function to alter a property.
alterFloatProperty()  : array<string|int, mixed>|float
Cast a value to float. If the value is an array, all elements in the array are casted.
alterGetDocument()  : mixed
Gets a document with a Documents model.
alterIntProperty()  : array<string|int, mixed>|float
Cast a value to integer.
alterJsonParseProperty()  : string|false|null
Decodes a JSON string
alterJsonStringifyProperty()  : string|false|null
Returns the JSON representation of a value
alterObject()  : mixed
Alter the passed-in object.
alterProperty()  : array<string|int, mixed>|object
Alters a specific property of the given document (array or object) using a defined transformation rule.
alterUrlProperty()  : string
Generates a document url.
getKeyValue()  : mixed
Gets the property value of with a specific key name in a document.
setKeyValue()  : array<string|int, mixed>|object
Set the property value of with a specific key name in a document.

Properties

$alters

The enumeration of all definitions to alter on the array or object key/value properties.

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

Methods

alter()

Alters the given document (array or object) based on the configured `$alters` definitions.

public alter(mixed $document) : mixed

This method determines the structure of the document and applies the appropriate transformation logic:

  • If the document is an associative array, each key listed in $alters is processed using alterAssociativeArray().
  • If the document is a sequential array (i.e., a list of items), the alteration is recursively applied to each item.
  • If the document is an object, its public properties are altered using alterObject().
  • If $alters is empty or no matching keys/properties are found, the document is returned unchanged.
Parameters
$document : mixed

The input to alter. Can be an associative array, object, or a list of items.

Tags
throws
ContainerExceptionInterface
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface
example 
class Example
{
    use AlterDocumentTrait;

    public function __construct()
    {
        $this->alters =
        [
           'price' => Alter::FLOAT,
           'tags'  => [ Alter::ARRAY , Alter::CLEAN ],
        ];
    }
}

$input = [ 'price' => '19.99', 'tags'  => 'foo,bar' ];

$processor = new Example();
$output = $processor->alter($input);

// $output:
// [
//     'price' => 19.99,
//     'tags'  => ['foo', 'bar'],
// ]
Return values
mixed —

The altered document, same structure as input.

alterArrayCleanProperty()

Clean an array of null or empty string elements.

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

alterArrayElements()

Alters all elements in an array.

public alterArrayElements(array<string|int, mixed> $array[, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>
Parameters
$array : array<string|int, mixed>
$options : array<string|int, mixed> = []
Tags
throws
DependencyException
throws
NotFoundException
throws
ContainerExceptionInterface
throws
NotFoundExceptionInterface
Return values
array<string|int, mixed>

alterArrayProperty()

Transform a string expression separated by semi-colon ';' to creates an array.

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

You can chain multiple alter definition to transform the content of the array, ex:

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

The previous example transform the 'category' string in an Array and after remove all null or empty array elements and JSON parse all elements.

Parameters
$value : mixed
$options : array<string|int, mixed> = []
$modified : bool = false
Tags
throws
ContainerExceptionInterface
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface
Return values
array<string|int, mixed>

alterAssociativeArray()

Alter the passed-in array.

public alterAssociativeArray(array<string|int, mixed> $document) : array<string|int, mixed>
Parameters
$document : array<string|int, mixed>
Tags
throws
ContainerExceptionInterface
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface
Return values
array<string|int, mixed>

alterCallableProperty()

Call a function to alter a property.

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

alterFloatProperty()

Cast a value to float. If the value is an array, all elements in the array are casted.

public alterFloatProperty(mixed $value[, bool &$modified = false ]) : array<string|int, mixed>|float 
Property::PRICE => [ Alter::FLOAT ] ,
Parameters
$value : mixed
$modified : bool = false
Return values
array<string|int, mixed>|float

alterGetDocument()

Gets a document with a Documents model.

public alterGetDocument(mixed $value[, array<string|int, mixed> $definition = [] ][, bool &$modified = false ]) : mixed
Parameters
$value : mixed
$definition : array<string|int, mixed> = []
$modified : bool = false
Tags
throws
ContainerExceptionInterface
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface

alterIntProperty()

Cast a value to integer.

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

If the value is an array, all elements in the array are casted.

Property::PRICE => [ Alter::INT ] ,
Parameters
$value : mixed
$modified : bool = false
Return values
array<string|int, mixed>|float

alterJsonParseProperty()

Decodes a JSON string

public alterJsonParseProperty(mixed $value[, array<string|int, mixed> $definition = [] ][, bool &$modified = false ]) : string|false|null
Parameters
$value : mixed
$definition : array<string|int, mixed> = []
$modified : bool = false
Return values
string|false|null

alterJsonStringifyProperty()

Returns the JSON representation of a value

public alterJsonStringifyProperty(mixed $value[, array<string|int, mixed> $definition = [] ][, bool &$modified = false ]) : string|false|null
Parameters
$value : mixed
$definition : array<string|int, mixed> = []
$modified : bool = false
Return values
string|false|null

alterObject()

Alter the passed-in object.

public alterObject(object $document) : mixed
Parameters
$document : object
Tags
throws
ContainerExceptionInterface
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface

alterProperty()

Alters a specific property of the given document (array or object) using a defined transformation rule.

public alterProperty(string $key, array<string|int, mixed>|object $document, string|array<string|int, mixed> $definition[, bool|null $isArray = null ]) : array<string|int, mixed>|object

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

  • A string representing a single Alter:: constant (e.g. Alter::FLOAT)
  • An array, where the first element is an Alter:: constant and the rest are parameters for that transformation

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::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::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 ])

$isArray : bool|null = null

Optional flag to indicate the type of document. If null, it will be inferred automatically.

Tags
throws
DependencyException
throws
NotFoundException
throws
ContainerExceptionInterface
throws
NotFoundExceptionInterface
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
];

$document =
[
    'price'    => '29.90',
    'tags'     => 'a;;b;',
    'meta'     => '{"active":true}',
    'url'      => '123',
    'discount' => 100,
    'rating'   => 0,
];

$result = $this->alterProperty('price', $document, Alter::FLOAT, true);
// 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)

alterUrlProperty()

Generates a document url.

public alterUrlProperty(array<string|int, mixed>|object $document[, array<string|int, mixed> $options = [] ][, bool|null $isArray = null ][, bool &$modified = false ][, string $propertyName = 'id' ]) : string
Parameters
$document : array<string|int, mixed>|object
$options : array<string|int, mixed> = []
$isArray : bool|null = null
$modified : bool = false
$propertyName : string = 'id'

The default property value to use to alter the url property (Default 'id').

Return values
string

getKeyValue()

Gets the property value of with a specific key name in a document.

public getKeyValue(array<string|int, mixed>|object $document, string $key[, bool|null $isArray = null ]) : mixed
Parameters
$document : array<string|int, mixed>|object
$key : string
$isArray : bool|null = null

Set automatically the document type if null or indicates manually if the document is an array (true) or an object (false).

setKeyValue()

Set the property value of with a specific key name in a document.

public setKeyValue(array<string|int, mixed>|object $document, string $key, mixed $value[, bool|null $isArray = null ]) : array<string|int, mixed>|object
Parameters
$document : array<string|int, mixed>|object
$key : string
$value : mixed
$isArray : bool|null = null

Set automatically the document type if null or indicates manually if the document is an array (true) or an object (false).

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

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results