Mapper Laravel Package

Product Decisions This Supports

• Upgrade sequencing for a platform dependency, not a feature. v3.0.0 is an infrastructure release. It unlocks Symfony 8.x compatibility ahead of a planned interface change, so the decision it informs is when to schedule the upgrade relative to other framework work — not whether to build anything.
• Framework-version support commitments. Dropping Symfony 6.x effectively sets a floor on the Symfony component versions your app can resolve. If you ship a library or a multi-version product, this release tells you which framework versions you can claim to support in your compatibility matrix and docs.
• Roadmap risk: a second breaking change is already announced. The maintainers state that supporting symfony/property-info or type-info 8.x requires an interface change planned for the next major. So v3.0.0 is explicitly an interim stop. Any plan that assumes one migration should be revised to assume two within a short window — budget the second one now rather than discovering it mid-quarter.
• Build vs. buy for object mapping. If your roadmap includes DTO/entity mapping, request-to-domain transformation, or hydration layers, this is the "buy" option: a maintained, actively tested mapper (note the PR activity: tests, static analysis, PHPStan, performance work) versus hand-written mapping code you'd own forever.
• Cache/invalidation planning. The xxh64 → xxh128 hashing change can alter generated-mapper cache keys. This is a deploy-runbook decision (cache clear/warm on release), not a product decision, but it must be in the rollout plan.
• Deployment/ops decisions. Version floor changes affect CI matrices, base images, and long-term-support branches. PMs should expect engineering to request CI and matrix changes alongside the bump.

When to Consider This Package

Consider it when:

• You have a Laravel or Symfony PHP application with meaningful mapping work — API resources ↔ domain models, third-party payloads ↔ internal DTOs, versioned contracts — and the mapping code is currently hand-written, duplicated, and drift-prone.
• You want conventions over configuration for mapping (nested objects, collections, constructor/property mapping) instead of per-field assignment code.
• You value a maintained library with visible test and static-analysis discipline; the release history shows ongoing test additions and PHPStan work, which is a reasonable proxy for maintainability.
• You are on, or moving to, Symfony 7.x/8.x components. On Symfony 7.x this release is straightforward. On Symfony 6.x it is out of scope.
• You need mapping behavior that is deterministic and cacheable — the hash-based caching and performance work in this release suggests a library designed for production hot paths.

Look elsewhere (or stay put) when:

• You are on Laravel 10.x or any stack resolving Symfony 6 components. Dropping Symfony 6 can produce dependency-resolution conflicts through laravel/framework's Symfony constraints. Verify with a real composer update in a scratch branch before committing; this is the single most likely blocker.
• Your mapping needs are trivial. A handful of DTOs is cheaper to hand-write than to adopt and upgrade a mapper.
• You need symfony/property-info or type-info 8.x today. v3.0.0 pins property-info to 7.x; the 8.x path requires an interface change deferred to the next major. If that's a hard requirement, this release does not satisfy it.
• You want upgrade stability. By definition, an interim major with an announced follow-up major is a poor fit for a codebase you cannot afford to touch twice in a short period.
• You need Laravel-native idioms (validation-integrated DTOs, Eloquent-aware casting) rather than a general-purpose mapper — a Laravel-specific data/DTO package may reduce glue code.
• You are mid-freeze. Defer to a window where a dependency bump and a cache clear can be scheduled together.

How to Pitch It (Stakeholders)

To executives: This is a maintenance release of an object-mapping library, not a product change. It buys us forward compatibility with the newest framework version and includes performance work, at the cost of dropping support for the oldest framework version. The material point is timing and effort: the maintainers have already announced a follow-up major release that will change an interface, so the honest framing is "two upgrades in the near term, not one." Recommend approving the work as scheduled technical-debt paydown with a known second installment, not as a one-off.

To engineering: v3.0.0 allows Symfony 8.x except symfony/property-info, which stays pinned to 7.x; full 8.x support for property-info/type-info requires an interface change deferred to the next major. Symfony 6.x support is dropped. Also note the xxh64 → xxh128 change, which may invalidate generated-mapper caches — plan a cache clear/warm on deploy. Required actions: run a resolution check against our actual Laravel/Symfony constraint set, update the CI version matrix, confirm no Symfony 6-only transitive constraints, and re-run the mapper test suite plus a smoke test on a hot path.

To the business, one line: Low feature value, moderate risk, real forward-compatibility value — approve the upgrade in a scheduled window, verify dependency resolution first, and pre-book capacity for the follow-up major.