Object Mapper Laravel Package

Product Decisions This Supports

• Where untyped data crosses a trust boundary. Any feature that ingests externally shaped data — third-party API responses, webhooks, CSV/flat-file imports, queue payloads, legacy SQL rows, config blobs — currently lands as array<string, mixed> and gets picked apart by $data['foo'] ?? null throughout the codebase. This package is a candidate for turning those boundaries into one typed object per payload.
• DTOs vs. domain entities. Supports an explicit decision to introduce a "data transfer object" layer distinct from Eloquent models, so domain code receives a guaranteed-shape object instead of a Model that may be partially hydrated, dirty, or missing attributes.
• Refactor sequencing. If the roadmap includes taming a legacy service, a migration off a monolithic controller, or adding a PHP 8 static-analysis gate, an object-mapping layer is often a prerequisite. Decide now whether that layer is bespoke, framework-native, or a package — retrofitting it after 40 new features is materially more expensive.
• Build vs. buy. The realistic comparison set is not "package vs. nothing" but "package vs. 200 lines of hand-rolled hydration vs. a heavier serializer." This nudges the decision toward a thin, swappable dependency rather than either an in-house utility nobody owns or a full serializer whose surface area dwarfs the problem.
• Testability and contract testing. Typed mappers make contract tests (fixture JSON in → expected object out) a natural unit of CI, which is a quality-bar decision as much as a technical one.
• Public API/event versioning. When external consumers hit your API or subscribe to your events, the mapping layer becomes the place where schema drift is absorbed and versioned — a product-compatibility decision, not just an implementation detail.

When to Consider This Package

Consider it when:

• You are on PHP 8.0+ and can use typed properties, constructor promotion, and readonly; the value proposition collapses on older runtimes.
• The dominant need is shape enforcement: given a known payload shape, produce a correct typed object or fail loudly. No validation rule engine, no cross-field business rules, no persistence.
• You want a dependency you can wrap in a 20-line internal interface and replace without touching call sites — the package is small enough that the abstraction cost is a single afternoon, not a sprint.
• The mapping targets are hand-written value objects you control, and you want mapping config to live next to (or inside) them rather than as annotations spread across a serializer config.
• You are prototyping an ingestion path and want to defer the "real" serializer decision without shipping raw array plumbing you will regret.

Look elsewhere when:

• You need validation, coercion of untrusted input, and localized error messages as one coherent story. That is a form-request/validation concern; a mapper that raises on a missing key is not a substitute for user-facing error reporting.
• You need deep graphs — cycles, lazy loading, polymorphic discriminators, back-references, collections of heterogeneous types. A mature serializer (Symfony Serializer, JMS, cuyz/valinor, or spatie/laravel-data on Laravel) has already solved the edge cases you will hit in month three.
• The workload is Eloquent-centric and Laravel-idiomatic. Framework-native conventions, model casts, and resource classes will be better understood by whoever inherits the code.
• It would sit on a critical path with no wrapper. 36 stars, zero dependents, and a 1.0 score signal a library with no adoption gravity and an unquantified bus factor. No dependents means nobody else's production traffic is exercising it, so you are the QA function. Adopt behind an internal port, pin the version, and budget a two-hour replacement spike if you adopt at all.
• The mapping is one or two payloads. Hand-write the constructor calls; a mapping configuration layer is overhead below roughly five to ten distinct types.

Adoption posture: treat as an evaluate/spike, not an adopt. Time-box a one-day proof against your two ugliest real payloads, including a failure case (missing key, wrong scalar type, null in a non-nullable field). Promote to "trial" only if it passes and you have the internal interface in place.

How to Pitch It (Stakeholders)

For executives (one paragraph). We have a recurring class of production defects where data from an outside system — a partner API, a webhook, a nightly import — arrives in an unexpected shape and the failure surfaces deep inside business logic, sometimes as corrupt records. The fix is a typed boundary: one object per external payload, so the failure happens at the edge, loudly, with a clear message. league/object-mapper is a small, MIT-licensed PHP package that does exactly that and nothing else. I am not recommending we standardize on it. Its adoption is effectively zero (36 stars, no downstream dependents), so it carries real maintenance risk. I am recommending we spend one engineering day proving it against our two messiest payloads and, if it holds, use it behind an internal interface so we can drop it for a replacement in an afternoon. The strategic value is the boundary discipline, not the library; the library is just the cheapest way to test whether that discipline pays for itself.

For engineering (summary). Scope is narrow: structured input in, strict typed object out. No validation engine, no persistence, no ORM coupling — which is precisely why it is low-risk to try and low-cost to remove. Required preconditions: PHP 8+ typed properties, hand-written DTO/target classes, and a wrapper (PayloadMapper interface with one implementation) so no call site imports the vendor namespace directly. Pin the version in composer.json; the project has no dependents, so assume we are the only ones exercising its edge cases and write fixture-based contract tests (raw payload → expected object) as part of the spike, not after. Known non-goals: validation and localized error messages stay in form requests; deep object graphs and polymorphic collections would push us toward Valinor or Symfony Serializer. Deliverable from the spike: a go/no-go with the two real payloads mapped, one failure case demonstrated, and a written estimate of what the hand-rolled alternative costs — so the build-vs-buy call is made on evidence rather than on the package's star count in either direction.