Hydrator Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for the data-mapping layer. HydratorBundle provides array/input → typed object hydration as reusable infrastructure. Adopting it lets you skip building and maintaining an in-house transformer/mapper, so engineering effort goes to domain features instead of glue code. Decision to make: adopt the package, extend it, or standardise on an alternative (e.g. spatie/laravel-data, hand-written fromArray factories).
• Feature scoping for nested data. v2 adds recursive/nested hydration and collection mapping, which directly affects what you can commit to: nested payload ingestion (orders with line items, tenant with nested settings), list endpoints, import pipelines, webhook normalisation, and read-model/DTO construction for CQRS-style flows. Without these features, each nested shape was custom code.
• API and integration roadmap. If your roadmap includes third-party integrations, CSV/JSON imports, or contract-first DTOs across teams, this package sets a convention for how payloads become objects — a standards decision, not just a library pick.
• Configurable mapping options as a product lever. Per-mapping options mean behaviour can vary by endpoint/domain without branching code, which lowers the cost of per-customer or per-partner variations.
• Maintenance and upgrade planning. 2.0.0 is a major release with likely breaking changes to the internal architecture and mapping API. This is a roadmap item: budget migration time, audit every call site, and expect the service-definition reorganisation to touch container/config wiring. Pin ^2.0 and treat it as a deliberate upgrade, not a patch.
• Extensibility investment. The orchestration/processing/hydration split makes domain-specific hydrators cheaper to add later — a reason to keep the dependency rather than replace it if you expect mapping rules to grow.
• Architecture review input. A restructured, DI-friendly mapping layer is a candidate standard for how all teams convert external input into domain objects; decide whether it becomes a platform convention or stays local to one service.

When to Consider This Package

Consider it when:

• You repeatedly map associative arrays (request bodies, queue messages, API/webhook payloads, file rows) into typed PHP objects across more than one feature.
• You need nested or recursive structures and lists of objects — the new v2 capabilities — rather than flat, single-level mapping.
• You want mapping behaviour configurable per context instead of duplicating mapper classes.
• The team is comfortable pinning a major version, reading source, and absorbing breaking changes at upgrade time.
• The mapping layer is not a hot path, or you are willing to benchmark before putting it behind high-throughput endpoints.

Look elsewhere when:

• The need is one or two simple mappings — plain constructors or ::fromArray() factories are cheaper than a dependency.
• You rely on Eloquent to hydrate models directly, or Laravel's request validation/API Resources already cover the need; this package maps input to objects, it does not replace persistence, validation, or serialisation.
• You require a large, mature ecosystem with published long-term support and broad community answers — this is a small, single-maintainer-style package; treat documentation depth, release cadence, test coverage, and security policy as adoption gates.
• Verify Laravel fit explicitly. The package is distributed bundle-style with reworked service-definition configuration files; confirm the container/DI wiring, supported PHP and framework versions, and whether it is Symfony-oriented before committing. If integration is awkward, that cost outweighs the mapping savings.
• Upgrade cost is unacceptable right now — if you are on 1.x and cannot absorb mapping-API changes, defer until a migration window exists.

Adoption gate for v2: confirm supported versions, review the README/examples for the new mapping API, run a spike on one real nested payload, and diff v1→v2 call sites to size the breakage.

How to Pitch It (Stakeholders)

For executives: This is a small, focused PHP library that turns raw input — API responses, queue messages, imports — into typed objects, removing a category of repetitive hand-written code we would otherwise build and maintain. The 2.0 release adds nested and collection mapping, which is what most of our integration and data-ingestion features actually need. The trade-off is a major-version upgrade with potential breaking changes, so the cost is a bounded migration effort, not new licensing or vendor lock-in; the dependency is thin and replaceable. Recommendation: pilot it in one ingestion feature, timeboxed, and compare against writing our own or using a Laravel-native alternative before making it a standard.

For engineering: v2 separates mapping orchestration, nested-data processing, and hydration, and moves service definitions into dedicated configuration files — the mapping layer is now easier to extend with domain-specific hydrators. Recursive/nested hydration, configurable mapping options, and collection mapping are available out of the box, so custom mapper classes and per-shape special cases should shrink. Before upgrade: pin ^2.0, verify the framework/container integration and supported PHP version, audit existing mapping call sites against the new API, and add regression tests around nested payloads. Flag any high-throughput mapping path for benchmarking, and if the package's maintenance cadence or docs look thin for a shared dependency, keep the abstraction boundary narrow so it stays swappable.