Hydrator Laravel Package

Product Decisions This Supports

• Build vs. buy at the data-mapping boundary. Every Laravel codebase eventually writes hand-rolled toArray() / fromArray() mappers for DTOs, API resources, and queue payloads. This package is a candidate to replace that bespoke glue, so the decision is framed as "adopt a small dependency" vs. "keep owning custom mapping code."
• Standardizing on immutable DTOs. Support for final, readonly, promoted properties, and constructor-less hydration removes the main practical objection engineering raises against readonly value objects. That unlocks a cleaner domain/transport separation across the roadmap.
• API contract stability and multi-representation APIs. Field renaming and exclusion via attributes lets the wire format diverge from the domain model without hand-written serializers — a direct lever on API versioning and backwards-compatibility work. As of 2.1.0, the new groups extension means one DTO can expose different field sets per context (public vs. admin, v1 vs. v2, internal event vs. external webhook) without cloning the model or writing per-endpoint serializers. That is a scope-control lever for API surface area, not just a serialization convenience.
• Privacy and GDPR roadmap. Crypto-shredding (encrypt per subject, delete the key to render data unrecoverable) is a product-level capability, not just a technical one: it supports "right to erasure" commitments without cascading deletes across every table and backup.
• Performance-sensitive surfaces. Caching layers and job payloads need fast round-tripping; a hydration-specialized library is easier to justify than a general-purpose serializer when throughput is on the roadmap.
• Pipeline governance for mapping behaviour. The 2.1.0 skippable middleware feature lets a mapping step opt out of middleware it doesn't need, and middleware generation lowers the cost of adding cross-cutting mapping behaviour consistently. Product implication: mapping policy (e.g., audit logging, redaction, version stamping) can be enforced centrally rather than re-implemented per mapper.
• Dependency policy. 20 stars and zero dependents is a vendor-risk data point. 2.1.0 shows continued activity (four PRs, three contributors, one of them a repeat contributor) but does not change the fundamentals: this is a small upstream you may have to fork. The decision includes whether the team is willing to own a small MIT library if upstream stalls.

When to Consider This Package

Consider it when:

• You have a DTO-heavy domain (or plan one) using PHP 8.2+, enums, date types, collections, and nested structures.
• Hydration happens at trusted boundaries — internal queues, caches, event snapshots, service-to-service payloads — where the input shape is already known.
• You need constructor bypass for final/readonly classes, or lazy hydration via PHP 8.4 lazy proxies for expensive object graphs.
• Attribute-driven rename/exclude and pluggable normalizers/extensions fit your conventions better than a config-heavy serializer.
• You need context-dependent output shapes from a single DTO — the 2.1.0 groups extension covers the "same model, different field set" case (public/admin, internal/external) that otherwise pushes teams toward parallel DTO classes or conditional serializers.
• You want mapping middleware as a first-class, governable pipeline (2.1.0 adds skippable middleware and middleware generation), rather than ad-hoc if branches inside mappers.
• Crypto-shredding materially advances a privacy deliverable.
• The team is comfortable owning a low-adoption dependency (small surface area, MIT, forkable).

Look elsewhere when:

• You need validation coupled to hydration (e.g., Spatie Laravel Data) — this package maps shapes, it does not validate untrusted request input.
• You need many formats (JSON, XML, CSV, YAML) or deep Symfony ecosystem integration — Symfony Serializer is the safer default. Note that groups and middleware now overlap meaningfully with Symfony Serializer's strongest arguments; multi-format support and ecosystem integration remain the deciding differences.
• You require community support, a security-response track record, or an SLA. Three contributors and a handful of dependents mean no ecosystem safety net, even with a healthy release.
• Laravel-native tooling (Eloquent integration, validation rules, first-party artisan commands) is a hard requirement. Middleware generation is a step toward developer tooling, but it is not Laravel integration.
• The payload is user-supplied and unvalidated; hydrating arbitrary input into objects without a validation gate is a security decision, not a convenience one.

How to Pitch It (Stakeholders)

To executives: This is a free, MIT-licensed utility that removes repetitive object-to-array mapping code and, notably, includes a data-erasure mechanism that supports our privacy commitments. The 2.1.0 release adds context-based field groups — one internal model can serve both a public and an admin representation — and a governable middleware pipeline, which reduces the API surface we have to maintain and makes mapping policy centrally enforced. The codebase is small enough to fork, so lock-in risk is low. The trade-off is unchanged: it is a young library with a very small community (three contributors), so we should treat it as an internal utility we're prepared to own — not a strategic platform bet. Approve a scoped pilot on internal boundaries (jobs, caches, event snapshots) rather than a company-wide standard.

To engineering: It does the one thing our hand-written mappers do badly — round-tripping objects without calling constructors, including final/readonly classes, promoted properties, and deeply nested graphs. Normalizers for enums, dates, collections, and array shapes come built in; rename/exclude is attribute-driven; lazy hydration uses PHP 8.4 proxies; the pipeline is extensible via guessers and extensions. 2.1.0 is additive and non-breaking: a groups extension for context-scoped field sets, skippable middleware so mapping steps can opt out of pipeline behaviour they don't need, and middleware generation to keep new pipeline components consistent. The Stryker mutation-testing badge, published docs/releases, and a steady minor-release cadence suggest genuine test rigor rather than a weekend project. Recommended posture: evaluate in one bounded service, adopt groups for the public/admin split if we go ahead, keep the abstraction behind our own interface so swapping to Symfony Serializer or Spatie Laravel Data stays a contained change, and do not use it as the validation layer for untrusted input.