Download the PHP package makermill/hydratype without Composer

HydraType

HydraType is a high-performance, compiled object hydrator and extractor for PHP. It turns arrays from databases, APIs, and queues into typed objects and those objects back into arrays, using generated PHP specialized for each class.

No schema, adapter, base class, interface, or setters are required.

High-throughput hydration without mapping boilerplate

The PHP class is the mapping definition. HydraType reads its property types and attributes, then compiles the work into direct object creation, conversion, and property access:

• hydrate public, protected, and private properties directly;
• convert scalar values and backed enums automatically;
• handle camel-case and snake-case data without adapters;
• hydrate and extract nested object graphs;
• compile selected transformations and assertions into individual properties;
• process batches through specialized hot paths; and
• pre-generate the complete cache for minimal production startup cost.

Use HydraType as a simple hydrator, or add behavior property by property. Features that a class does not select generate no work on its hydration path.

Install

HydraType requires PHP 8.2 or newer.

Quick start

Given an ordinary class and a backed enum:

Hydrate snake-case or camel-case data without configuring an adapter:

The return type is inferred as User. HydraType converts values to declared property types and writes private and protected properties directly.

Extract the object to an array:

Use the optimized batch paths when working with several objects:

For an especially focused hot path, $hydra->hydrator(User::class) returns a reusable class-specific hydrator. See hydration and extraction for naming, type conversion, batch behavior, nullability, and constructor semantics.

Performance is the feature

HydraType reflects each class once and generates executable PHP specialized for that exact object shape. Repeated hydration is reduced to object creation, inline conversion, and straight-line property assignment. Private properties are accessed through reusable class-scoped closures, and batch operations select a writer once for the complete batch.

Optional features follow a strict rule: a class that does not select a feature does not pay for it during hydration or extraction. There are no runtime registries, mapping walks, or mutator dispatch calls in the ordinary property path.

This is not a generic runtime mapping pipeline with a cache placed in front of it. The cache contains the optimized implementation for the target class. The generated-code choices are backed by cross-version microbenchmarks and direct competitor benchmarks. See the architecture for the rules that protect the fast path.

Performance comparison

In the maintained benchmarks, HydraType was fastest for private-property hydration on PHP 8.2 and PHP 8.5. Its public-property path was effectively tied for fastest on PHP 8.2 and fastest on PHP 8.5. The optimized batch path came within 16–23% of equivalent handwritten PHP.

The maintained competitor benchmark measures warmed hydration of correctly typed five-property arrays into new objects with private promoted properties or ordinary public typed properties. These are focused hot-path comparisons rather than comparisons of every feature offered by each library. Relative values use HydraType as the 1.00x baseline.

Private properties

Public properties

HydraType was fastest for private properties in both environments and for public properties on PHP 8.5. The PHP 8.2 public paths were effectively tied: HydraType and Ocramius were separated by about 1% and exchanged order between individual rounds. Ocramius directly assigns keys that are present and skips missing keys. HydraType additionally checks required keys and coerces values to the declared property types.

Faster still in batches

In the maintained batch benchmark, hydrateMany() is 37% faster per object than repeated hydrate() calls on PHP 8.2 and 29% faster on PHP 8.5. In a like-for-like comparison with handwritten PHP, it comes within about 23% and 16% respectively.

See the benchmark methodology and complete conclusions.

Opt-in behavior

Attributes add behavior only to the properties that select it:

• Mutators transform incoming values and may also transform extracted values.
• Assertions are compiled fail-fast guards, not a general validation system.
• Optional preserves a declared property or promoted parameter default when the input key is absent.
• Backed enums and concrete nested objects work without attributes.

See assertions, and nested hydration for their complete behavior and extension contracts.

Production fast path

The default CacheMode::Auto is convenient during development: it generates a missing hydrator and refreshes one whose source dependencies changed.

For production, warm all application entry points during build or deployment:

Keep the warm-up list in sync

As an application grows, manually maintaining every class passed to warm() is easy to forget. HydraType Tools generates this class list from the project source. See its documentation for current installation and usage.

Whether the class list is maintained manually or generated, use the warmed cache in read-only mode at runtime:

Read-only mode skips source reflection, dependency fingerprinting, locks, and all cache writes. It fails immediately when an expected artifact is missing. The generated hydration path is identical in automatic and read-only modes.

See cache and production deployment for invalidation, concurrency, nested warm-up, custom directories and namespaces, and selective cache clearing.

Supported behavior at a glance

Unbacked enums, union types, intersection types, inferred collections of nested objects, and runtime object-graph cycles are not supported.

Documentation

• Hydration and extraction — naming, conversions, batches, nullability, construction, and errors.
• Nested hydration — recursive objects, HydrateAs, cache behavior, and boundaries.
• Mutators — every built-in transformation and the custom extension contract.
• Assertions — built-in and custom fail-fast guards.
• Cache and production deployment — modes, warm-up, invalidation, concurrency, and clearing.
• Public API boundary — supported consumer and extension types.
• Architecture — generated-code rules and structural verification.
• Benchmark conclusions — measurements behind the implementation choices.

Development

Install dependencies and run the complete checks:

The repository includes matched PHP 8.2 and PHP 8.5 Docker environments:

The competitor benchmark can be run against either image:

Individual test, static-analysis, coverage, and benchmark commands are defined in composer.json.