Weave Code
Object Hydrator Laravel Package
eventsauce/object-hydrator
Magic-less object hydration and serialization for PHP. Map arrays/decoded JSON to DTOs, commands, queries, and events by inspecting constructors and public getters—no private-property reflection. Supports custom keys, casting, and optional code generation for speed.
eventsauce/object-hydrator converts structured data (e.g. decoded JSON) to typed PHP objects and back—without “magic” reflection. It inspects your constructor to hydrate values as you’d write by hand, and serializes via public properties and getters, making it ideal for DTOs, Commands/Queries, and Event payloads.
Designed for convention-based mapping (not validation), it supports ahead-of-time resolution and optional code generation for near-zero runtime overhead.
- Constructor-based hydration (no private property reflection)
- Serializer using public properties + getter methods
- Custom key mapping and mapping from multiple keys
- Property casting for nested objects/value types
- Performance-focused with code generation support
Frequently asked questions about Object Hydrator
- Can I use this hydrator to replace Eloquent models entirely in Laravel?
- No, this package is designed for domain objects, not Eloquent models. While you can hydrate Eloquent models, it’s not recommended—Eloquent already handles hydration. Use it for custom aggregates, value objects, or DDD entities alongside Eloquent.
- How does this hydrator work with Laravel’s Form Request validation?
- The hydrator validates data via constructor promotion and type hints, but it doesn’t replace Laravel’s validation rules. You can extend `FormRequest` to hydrate payloads after validation, e.g., `$request->hydrate(Payment::class)`. For complex objects, it may reduce boilerplate.
- What Laravel versions and PHP versions does this package support?
- Requires PHP 8.0+ (for constructor property promotion and strict typing). Works with Laravel 8.50+ or later, as it leverages Symfony’s PropertyAccess (already bundled with Laravel). No Laravel-specific dependencies mean minimal version conflicts.
- Will this hydrator slow down my application if I use it everywhere?
- No, it’s lightweight (~100KB) with zero dependencies. Performance impact is negligible unless you’re hydrating thousands of objects per request. Benchmark in your context, but it’s optimized for high-throughput systems like event sourcing or API gateways.
- How do I handle nested objects or complex hydration scenarios?
- Use the `HydrationContext` to define custom mappings for nested objects or edge cases. For example, map a JSON array to a collection of value objects. The package supports recursive hydration out of the box, but complex cases may require custom `HydratorInterface` implementations.
- Does this package work with EventSaucePHP/EventSourcing?
- Yes, it’s a natural fit for Event Sourcing. Use it to reconstruct aggregates from serialized events (e.g., JSON payloads) while enforcing immutability and strict typing. The hydrator aligns with EventSauce’s domain-driven approach.
- How do I integrate this with Laravel’s service container?
- Manually bind the hydrator to the container in a service provider. For example: `$app->bind(PaymentHydrator::class, fn() => new ObjectHydrator());`. No built-in Laravel service provider exists, so you’ll need to DI it yourself or create a macro for convenience.
- Can I use this for API request DTOs instead of Laravel’s Form Requests?
- Absolutely. Replace manual `$request->input()` + `new Class($data)` with the hydrator to enforce type safety and immutability. For example, hydrate a `CreateOrderRequest` payload directly into an `Order` aggregate root.
- What are the alternatives to this hydrator in Laravel?
- For DDD, consider `spatie/laravel-data` (simpler but less strict) or `league/value-object` (for immutable objects). For Eloquent-specific hydration, stick with Laravel’s built-in features. This package is unique in its strict typing and Event Sourcing alignment.
- How do I test hydrated objects in PHPUnit?
- Mock the hydrator by injecting a `HydratorInterface` into your service layer. Use `createMock(ObjectHydrator::class)` and configure it to return test objects. For unit tests, focus on validating business logic rather than hydration itself, as it’s deterministic.
Weaver
How can I help you explore Laravel packages today?