Oihana PHP

AlterHydratePropertyTrait uses \oihana\reflect\traits\ReflectionTrait

Hydrates an array value into a typed object instance during property alteration.

This alteration is declared with the Alter::HYDRATE type. It is used in property transformation pipelines to turn a raw associative array (for instance the decoded payload of a nested document) into a real object of a given class, so that downstream code works with strongly-typed instances instead of loose arrays:

Property::GEO => [ Alter::HYDRATE , GeoCoordinates::class ] ,

Two hydration strategies are used depending on the target class: classes extending Thing are built directly through their constructor, while any other class is populated through ReflectionTrait::hydrate() (reflection-based property mapping). The input is normalized beforehand (configurable through CleanFlag), and an empty normalized value yields null.

The $modified flag is set to true whenever the resulting value differs from the original input.

Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Methods

alterHydrateProperty()  : mixed
Hydrate a property value into a specific class instance using reflection.

Methods

alterHydrateProperty()

Hydrate a property value into a specific class instance using reflection.

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

This method transforms a raw value (typically an array) into an object of the specified class. If the input value is an array, it can be normalized and then hydrated using either the Thing constructor or the ReflectionTrait::hydrate() method depending on the class type.

Behavior

  • If $value is not an array, it is returned as-is.
  • If $value is an empty array, the method returns null (by default).
  • If $schema refers to a class extending Thing, the object is created directly via its constructor.
  • Otherwise, hydration is performed via ReflectionTrait::hydrate().
  • The $modified flag is set to true if the resulting value differs from the input.

Usage Example

Property::GEO => [ Alter::HYDRATE, GeoCoordinates::class ],

Custom Normalization

You can specify a custom normalization flag as a third element in the definition:

[ Alter::HYDRATE, GeoCoordinates::class, true , CleanFlag::ALL ]

By default, the value is normalized using: normalize() with flags CleanFlag::DEFAULT | CleanFlag::RETURN_NULL.

Parameters
$value : mixed

The original value to hydrate. Can be a scalar, array, or object.

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

The alter definition, expected as:

[
    0 => string|null $schema,   // Fully qualified class name to hydrate into
    1 => bool        $normalize // Whether to normalize the value before hydration (default true)
    2 => int         $flags     // Optional CleanFlag bitmask
]
$modified : bool = false

Reference flag set to true if the resulting value differs from the original.

Tags
throws
ReflectionException

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

example 
use oihana\models\traits\alters\AlterHydratePropertyTrait;
use org\schema\GeoCoordinates;

class Place
{
    use AlterHydratePropertyTrait;
}

$place    = new Place();
$modified = false;

$geo = $place->alterHydrateProperty
(
    [ 'latitude' => 48.85 , 'longitude' => 2.35 ] ,
    [ GeoCoordinates::class ] ,
    $modified
);
// $geo instanceof GeoCoordinates === true
// $modified === true

// A scalar is returned untouched
$raw = $place->alterHydrateProperty( 'not-an-array' , [ GeoCoordinates::class ] , $modified );
// $raw === 'not-an-array'
Return values
mixed —

The hydrated value, possibly an instance of $schema, or null if empty.

On this page

Search results