Download the PHP package rammewerk/hydrator without Composer

Rammewerk Hydrator - A strongly typed hydrator

The Rammewerk Hydrator is a fast, reflection-based hydrator for PHP 8.4+, built to effortlessly map arrays onto PHP objects with minimal configuration.

It’s not an ORM - no annotations or heavy frameworks - just a simple yet powerful mapper. It even includes a lazy-loading HydratorCollection for handling large datasets.

Installation

Basic usage

Let's consider a simple entity/dto:

We can populate this from an array:

In return, we got a typed entity.

This might be useful to automatically convert data from database to an entity, or from an API etc.

Features

• Reflection-based hydrator with caching
• Converts scalars, date/time objects, enums, union/intersection types
• Handles promoted/readonly properties, default/null values
• Automatically hydrates nested objects
• HydratorCollection for quickly hydrating large datasets
• Full IDE autocompletion

Benefits

• Enhanced type safety via entities
• Automatic class mapping from arrays
• Clear IDE type hints
• Improved code quality

Allowed Property Types

The hydrator ensures each property is set to its declared type by converting raw data as needed (e.g., booleans stored as integers). It supports:

• Built-in types: string, int, float, bool, array
• Date types: DateTime, DateTimeImmutable, DateTimeZone
• Backed enums - Using the enum’s from() method
• Unit enums - Using the enum’s case name as matching value
• Union/Intersection types (e.g., string|int, InterfaceA&InterfaceB)
• Classes (e.g., public AnotherClass $class) — nested objects are hydrated if valid data is provided
• Arrays of classes via the mapArray() method. More about nested objects here.

Note: One should try not to use union/intersection types, as they may lead to unexpected results. Use with caution.

Nested hydration

If the hydrator encounters a property of type class, it will hydrate the class if given data is an array.

To handle an array of classes, you can use the built-in mapArray method:

Hydrator Collection

Collections are lazy-loaded, and will only hydrate the entities when you iterate over them. This is useful for large datasets, as it will only hydrate the entities that are actually needed. If needed all at once, you can use the toArray() method.

Constructor parameters

When your class uses constructor parameters, the hydrator automatically resolves them, but with a few rules:

• Promoted parameters (public string $firstName): Treated like properties, but assigned through the constructor. If no default is set, a dataset value is required.
• Non-promoted parameters (string $firstName): These aren’t set directly from the dataset. They’re constructed with their default or null if nullable. If a non-promoted parameter is non-nullable and lacks a default, it throws an exception. After construction, a corresponding property (if it exists) is separately hydrated from the dataset.

Example:

Read more on this below in the section about object design.

Read only properties

To add readonly properties, they must be initiated through the constructor.

Why Use the Hydrator?

The hydrator helps convert raw data (e.g., from a database) into typed PHP objects without tedious manual checks. It enforces strict types, simplifies property access, and makes your code more maintainable.

Without hydrator

With Hydrator

In the hydrator version, your IDE can autocomplete $user properties because it knows each user is a User object. It also ensures that only defined properties on the User entity are hydrated - no unexpected data creeping in.

There’s no hidden __call() magic or dynamic property illusions - just strictly typed objects, so you always know exactly what data you’re working with.

To achieve this, simply return a HydratorCollection from your repository:

Now you get a collection of actual User objects, each property strictly typed, making your code cleaner and more reliable.

Be Mindful of Object Design

While the hydrator is powerful, it doesn’t replace good object design.

Avoid making your classes reliant on the hydrator by declaring uninitialized or non-optional properties without defaults. If you attempt to access such properties before the hydrator sets them, you’ll encounter exceptions. Instead, use sensible defaults or optional properties, and ensure your constructor aligns with how data is actually provided. See below for an example.

Set reasonable defaults:

The $name property is nullable, but it’s initialized with an empty string. This means the hydrator will never set it to null; instead, it will use '', even when null is provided. To allow null values, initialize the property like this:

Define Required Properties via Constructor

Avoid declaring non-optional properties without initializing them. This is bad practice as it can lead to uninitialized properties.

Best Practice: Define required properties through the constructor. If a property should be read-only, use the readonly keyword in the constructor’s promoted parameters.

Benefits:

• Ensures Initialization: All required properties are set upon object creation.
• Immutability: Using readonly enforces that certain properties cannot be modified after initialization.
• Clear Intent: Makes the code more predictable and easier to understand.

Limited Hydration for Non-Promoted Parameters

Non-promoted constructor parameters aren’t automatically hydrated because they often don’t match a specific property or may be used for computed values. The hydrator’s role is to fill properties, not infer custom constructor logic.

If you need non-promoted parameters, give them defaults, make them nullable, or manually instantiate your object before hydration:

Preserving Properties Set by the Constructor

The hydrator won’t overwrite properties already set to values different from their default. This prevents overwriting values explicitly set by your constructor. For example:

If the hydrator is given ['age' => 20], it won’t override age (already set to 18 by the constructor). This behavior ensures constructor-defined values are respected.

Hydrator Callback for More Customizable Hydration

The hydrator can be used as a callback, returning the hydrated object. The first parameter of hydrate() is an array of data to hydrate with, and the second parameter is a callback that customizes hydration.

Note: Data given in the first parameter will override values returned by the callback.

Example Usage

By using this approach, you can define a default set of properties in the first parameter, while the callback provides additional values that are used unless explicitly overridden by the initial array.

Error handling

All exceptions extend Rammewerk\Component\Hydrator\Error\HydratorException. Catch them to manage invalid data.

Contribution

If you have any issues or would like to contribute to the development of this library, feel free to open an issue or pull request.

License

The Rammewerk Hydrator is open-sourced software licensed under the MIT license.

Keywords: DTO, mapper, data-mapper and populator

Converters

• String
  • Scalar (int, float, bool, string)
  • Null will be converted to empty string, unless nullable
• Int
• Float
• Bool
• DateTime
• DateTimeImmutable
• DateTimeZone
• Enum
• Union
• Intersection
• Array