Object Mapper Laravel Package

Product Decisions This Supports

• Build vs. buy for DTO mapping: This is a credible "buy" answer to the recurring "who writes the mapper?" question. If your API surface is growing and controllers/services are accumulating hand-written new UserResponseDTO($user->name, $user->email, ...) blocks, adopting a declarative mapper is a decision you can defend on maintenance cost alone — one mapping definition instead of N call sites.
• API contract / domain separation roadmap: Directly supports a decision to stop serializing Eloquent models straight to JSON. Declarative mapping makes "domain model → response DTO" a first-class, reviewable artifact rather than an implicit side effect of toArray().
• Consolidation vs. proliferation of mapping code: If you currently have three ad-hoc mappers (API resources, queue payload builders, form → command objects), this is a candidate to unify them under one attribute-driven mechanism. That reduces the number of places a field rename must be chased.
• Sequencing for modernization work: Useful as a low-cost enabler when you're extracting a service layer, splitting an API version, or introducing command/query objects. It lets you move incrementally without a big-bang refactor of every controller.
• Explicit non-decision: This is not a reason to standardize on Symfony DI, nor a reason to migrate off Eloquent hydration. Keep those out of scope; the package should be evaluated purely as a mapping utility bolted onto an existing Laravel app.

When to Consider This Package

Adopt if:

• You have many DTO classes with similar-but-not-identical shapes to models (renamed fields, nested objects, collection-of-DTO cases) and the mapping code is measurably a maintenance burden.
• Your team is already comfortable with a PHP 8 attributes style of configuration and you want mapping rules to live next to the class, not in a separate config file.
• You want a Symfony-maintained, MIT-licensed component with a documented release/BC policy and a real security process — and you're willing to accept that this is early-stage.
• You can absorb the integration cost: there is no official Laravel bridge. Budget for a small service provider binding the mapper interface, and verify attribute semantics and exceptions against the docs, not the marketing.

Look elsewhere if:

• Adoption signals matter to you. 36 stars and zero dependents is a thin signal for a production dependency. The upside is Symfony's release discipline; the downside is that you will likely be the one finding the edge-case bugs. Treat this as "early adopter," not "safe default."
• You want batteries-included Laravel ergonomics. spatie/laravel-data gives you DTOs, validation, casting, and request integration in one package — more opinionated, but far less glue for a Laravel team. If you don't need the mapping layer in isolation, this package is the harder path.
• API version churn is a concern. The component went from 7.3 BETA to 8.1 in a compressed window, with Symfony 8 requiring PHP ≥ 8.4. Pin the version, and confirm your PHP upgrade cadence can keep pace.
• Your mapping needs are trivial. Simple 1:1 field renames, or cases where Model::fill() / Eloquent casts / API Resources already do the job — this is overkill and adds a dependency with a learning curve.
• Performance is on the critical path on high-RPS endpoints. Benchmark first; the component caches attribute metadata in memory, but you should still measure against hand-written mappers before committing.
• You need runtime-defined/dynamic shapes (JSON-Schema-driven APIs, EAV). Serializer-style tooling is a better fit.
• Also verify the release metadata — the dates in the package feed look anomalous (a release dated in the future). Confirm the actual current stable version and its support window before writing it into a plan.

How to Pitch It (Stakeholders)

To executives: "We're proposing a narrowly scoped dependency to remove a recurring tax on every API change: the manual copying of data between our database models and the objects we return to clients. Today each new endpoint re-implements that copying by hand, which is where field-rename bugs and review churn come from. This lets us describe the conversion once, next to the class, and reuse it. It's MIT-licensed, maintained by the Symfony project, and it's a library — not a framework commitment. The risk is low and reversible: it's additive, we can pilot it on one module, and we can rip it out without touching the database or the domain model. The honest caveat is that it's a young component with little third-party adoption, so I'm recommending it as a scoped pilot with a named owner, not as a house standard."

To engineering: "This replaces hand-written mapping with attributes — field renames, nested objects, collections, conditional and custom transforms. It's a single composer dependency, no framework lock-in; we wire the mapper into the container ourselves with a small provider. Two things to weigh honestly: (1) it's early — 36 stars, no dependents — so assume we'll hit unpatched edge cases and should pin the version; (2) spatie/laravel-data is the Laravel-native alternative and comes with validation and casting. Proposed approach: pilot on one bounded context with complex nested DTOs — the case where a hand-written mapper hurts most — and compare code volume, error surface, and runtime cost before deciding. If the pilot is ambiguous, we default to the Laravel-native option."

To architects: "The architectural value is enforced separation between persistence models and outbound contracts, expressed declaratively so the mapping is reviewable in one place. It fits cleanly where we have distinct read/write shapes or are extracting a service layer. The trade-offs: a young component with an API that moved quickly across 7.x→8.x, a PHP 8.4 floor on the current major, and an integration we own end-to-end since there's no Laravel bridge. My recommendation is to standardize the pattern — explicit DTOs and one mapping mechanism — while treating the specific library as swappable. Decide the pattern now, choose the implementation after the pilot."