Weave Code
Hydrator Laravel Package
yiisoft/hydrator
Yii Hydrator populates typed objects from arrays and other input using attributes and property mapping. It handles type casting, nested hydration, and dependency injection, offering PHP and Laravel apps a fast, flexible alternative to manual DTO construction.
Create and populate objects with type casting, mapping and dependencies resolving support.
Frequently asked questions about Hydrator
- How do I install yiisoft/hydrator in a Laravel application?
- Install it with Composer using composer require yiisoft/hydrator. It is a framework-agnostic Yii3 component, not a Laravel package, so you register a service provider that binds HydratorInterface as a singleton with your handler set and cache. Laravel's container already implements PSR-11 and Laravel's cache repository implements PSR-16, so no adapters are needed.
- What is yiisoft/hydrator used for in Laravel?
- It turns untyped input such as request payloads, queue messages, webhook bodies, and third-party API responses into typed, constructor-validated DTOs. It provides type-aware casting, nested object hydration, and attribute-driven property mapping. It is useful for building command objects, request DTOs, and configuration models without repetitive assignment code.
- Does yiisoft/hydrator work with Laravel 10, 11, and 12?
- The package requires PHP 8.1+ and is framework-agnostic; Laravel integration relies on the PSR-11 and PSR-16 interfaces Laravel already implements. The technical assessment states that the PHP and framework version requirements line up with the supported Laravel 10/11/12 matrix. Still, prove casting parity with contract tests because the package's semantics may not match Laravel's Validation and Cast behavior exactly.
- How does yiisoft/hydrator compare to spatie/laravel-data?
- spatie/laravel-data is Laravel-native, has vastly larger adoption, and integrates with validation, resources, and Eloquent out of the box. yiisoft/hydrator is a smaller, Yii-flavored, container-driven component with a leaner core and no Laravel coupling in the domain layer. Choose it only if you isolate it behind your own interface; it is a component, not a platform bet.
- How do I handle hydration exceptions so Laravel returns 422 instead of 500?
- Hydration failures throw package exceptions, not ValidationException, so Laravel will not automatically produce 422 JSON responses. You must add an exception-mapping layer that catches hydrator exceptions and converts them into ValidationException or your own 422 response. Without that layer, unhandled hydration failures become 500s in production.
- Is yiisoft/hydrator safe for mass assignment?
- The hydrator will populate whatever the reflection-built plan allows, so without explicit per-DTO allowlists or readonly DTOs you can reintroduce the vulnerability class Laravel's $fillable was designed to prevent. Use readonly DTOs or explicit mapping allowlists for input objects. Treat request DTOs as closed shapes rather than open bags of properties.
- How does yiisoft/hydrator cache hydration plans and what should I watch in production?
- Its two-stage pipeline builds a reflection-based hydration plan per class, then handlers apply casting and mapping; plan caching expects a PSR-16 simple cache, which Laravel's cache repository implements. Bind that cache with a one-line binding and use a shared, versioned cache namespace. A stale plan cache after a DTO shape change is a production-breaking failure mode that will not appear locally or in CI unless cache behavior is exercised. Flush or version the cache keys on every deploy.
- Does yiisoft/hydrator support enums, DateTimeImmutable, union types, and nested DTOs?
- It provides type-aware hydration for scalar values, typed and nullable properties, and nested objects from nested arrays, and it is extensible through interfaces for custom hydration logic. The assessment warns that nullables, enums, DateTimeImmutable, union and intersection types, and nested collections of DTOs may not match Laravel's Validation and Cast semantics exactly. Prove parity with contract tests instead of assuming identical behavior.
- How do I test a Laravel app that uses yiisoft/hydrator?
- Write contract tests around your own façade covering casting parity, nested hydration, enums, nullables, and exception mapping. Exercise plan-cache behavior in CI, including stale cache after DTO changes, not just in local runs. Pin exact package versions and avoid calling the package API directly in application code so tests target your stable interface.
- Is yiisoft/hydrator actively maintained and what are the BC risks?
- It is a single-vendor Yii3 component with a small star count and a Yii3 release cadence, so pre-1.x-style backward-compatibility churn is plausible. Ask for the named maintainer and the project's BC policy before committing. Mitigate the risk by pinning exact versions and depending on your own façade rather than the package API directly.
Weaver
How can I help you explore Laravel packages today?