Download the PHP package squidit/array-to-object without Composer

Object Hydrator

Hydrate typed objects from associative arrays, dotted arrays, or DTO-like source objects by mapping input keys or property names to corresponding typed target properties. The library also includes a helper base class for DTO-to-JSON output.

The supplied keys or source-object property names must match the names of the target object properties.

Installation

v3.* (PHP 8.4+)

v2.* (PHP 8.2 / 8.3)

Usage - example (multi dimensional array):

Usage - example (array dot notation):

output

If you only need to convert dotted keys into a nested array, use DotNotationToMultiDimensional directly:

Pass DotNotationFormat::EXPLODE as the second constructor argument when using explode-style dotted keys.

Usage - example (DTO/object input):

When the source data already arrives as an object, use DtoToObject. The source-object property names must match the target-object property names. Nested hydration and type casting work the same way as with array input.

Hydrating multiple objects

ArrayToObject, DotNotationArrayToObject, and DtoToObject all provide hydrateMulti() for indexed lists of source records:

Nested objects

If a class property contains a nested object, the hydrator can infer the object type by reading the property type.

In the example below, the Car::class contains a named property manufacturer which is of type Honda::class. When hydrating, we need to provide all data required to create a Honda object.

Nested objects: Array of objects

If a class property contains an array of objects, we need to add a property attribute:
SquidIT\Hydrator\Attributes\ArrayOf([CLASSNAME]).

In the example below, the Honda::class contains a property employeeList which should contain an array of Employee::class objects.

By adding the property attribute SquidIT\Hydrator\Attributes\ArrayOf(Employee::class) our hydrator knows how to hydrate array data found under the 'employeeList' object property.

Default values

When input omits a property, the hydrator uses the target object's default value when one exists. Defaults can come from constructor-promoted properties or regular declared properties.

Object defaults are cloned during hydration, so each hydrated object receives its own default object instance instead of sharing mutable state with other hydrated objects.

Hydration lifecycle

Target objects are created without executing the constructor body, then their typed properties are assigned directly. This means reflected default values are honored, but constructor side effects and constructor-only validation logic do not run during hydration. Use ObjectValidatorInterface for checks that must happen after hydration.

Object validation

If an object needs validation after hydration, implement SquidIT\Hydrator\Interface\ObjectValidatorInterface.

The hydrator calls validate() after all properties have been hydrated. When validation fails, throw a \SquidIT\Hydrator\Exceptions\ValidationFailureException. The supplied PathTracker can be used to include the property path in the exception message, including nested object and array positions.

User-safe error messages

By default, hydration errors include implementation detail that is useful for developers. If the message may reach an end user, enable safe error messages when creating the hydrator:

With safe messages enabled, a missing nested value is reported using a user-facing property path, for example: Path: manufacturer.employeeList[0].employeeName - no data supplied for required property.

DTO to JSON output

When a DTO needs predictable JSON output, extend SquidIT\Hydrator\Abstract\AbstractObjectToDto. This abstract class is specifically intended to help DTOs prepare JSON-friendly output through PHP's JsonSerializable flow.

Public and protected properties are included automatically. DateTimeImmutable values are formatted as Y-m-d\TH:i:s.u, backed enums are converted to their scalar values, and private properties are excluded.

If a DTO needs a different JSON date format, override the protected format constant:

Type casting/juggling array values into object properties

It is important to note that the hydrator will only work on classes that only contain typed properties. If a non typed property is found an SquidIT\Hydrator\Exceptions\AmbiguousTypeException exception will be thrown.

The hydrator supports casting into the following property types

int:

if a string contains only digits (plus and minus signs are allowed)

bool:

The following values will be cast to true

• 1 [int]
• 'true' [string]
• '1' [string]
• 'y' [string]
• 'yes' [string]

The following values will be cast to false

• 0 [int]
• 'false' [string]
• '0' [string]
• 'n' [string]
• 'no' [string]

DateTimeImmutable::class:

Any string value supported by strtotime()
please note: as author of this library I feel no need to support the DateTime::class

BackedEnum:

Any integer of string backed enum value

UnionTypes:

:x: Union types are not supported because we are unable to infer concrete object type implementation.

Upgrading

Update v1. => V2.

Interface change

Adjust all references:

• From: \SquidIT\Hydrator\ArrayToObjectHydratorInterface
• To: \SquidIT\Hydrator\Interface\ArrayToObjectHydratorInterface

Update v2. => v3.

• Drops support for PHP 8.2 and 8.3, requires PHP 8.4+.
• Hydration hot path was reworked. Cached/warm hydration benchmarks are roughly 30% faster than v2, and ~40% faster than v2 prior to its mutation-removal patch. No public API changes; existing v2 code keeps working on PHP 8.4+.