Laravel Package Laravel Package

Product Decisions This Supports

• Build vs. buy for the "typed boundary" layer. Every integration-heavy product eventually needs a place where untrusted external JSON becomes a typed PHP object. This package is a candidate answer to that build-vs-buy question: instead of hand-rolling $data['customer']['address']['line1'] ?? null traversal in controllers, you declare a class and let the mapper hydrate it. The decision it informs is whether that boundary lives in a bespoke internal utility, a battle-tested OSS library, or nothing at all (arrays everywhere).
• Standardizing DTO hydration across integrations. If the roadmap includes multiple partner APIs, webhooks, or a public ingestion endpoint, the PM decision is "do we adopt one mapping convention now, before the fifth integration diverges?" This package plus its underlying JsonMapper library gives a consistent, annotation/attribute-driven convention.
• Scoping integration work more accurately. Teams that write manual mapping code consistently underestimate payload-handling effort and defect rates (nulls, type coercion, nested arrays, date strings). Adopting a mapper is a schedule-and-quality lever: it converts "wire up partner API" from an open-ended task into a bounded one.
• Prioritizing where a Laravel-native wrapper beats a framework-agnostic library. The wrapper's value is container binding, publishable config, and Laravel-idiomatic service resolution. That is a real but thin value proposition — it justifies adoption only when the team is already Laravel-standardized and wants zero bootstrapping code.
• Platform-version gating as a roadmap input. Release 3.0.0 makes this a PHP 7.4+ / Laravel 11+ dependency. If any product line still runs Laravel 10 or PHP 7.3, adoption on that line is blocked unless you stay on 2.x — which is now on a separate, likely unmaintained branch. That is a portfolio-level decision about when to retire old framework versions, not just a library pick.
• Assessing vendor/OSS risk as a roadmap input. With ~25 stars, zero dependents, and a single-maintainer profile, this remains a "low-opportunity, low-adoption" library despite a high quality score. Encouragingly, 3.0.0 shows sustained maintenance behavior (CI modernization, changelog/release automation, framework-version currency) rather than a drive-by release. The PM decision is about acceptable dependency risk for a core path versus a peripheral one — and about budgeting a thin abstraction so the choice stays reversible.
• Not a decision driver for validation, request casting, or API resource shaping — those are separate concerns and belong elsewhere.

When to Consider This Package

Consider it when:

• You already depend on the underlying JsonMapper library (or are about to) and want Laravel container/config integration rather than manual instantiation in every service.
• You are on Laravel 11, 12, or 13 and PHP 7.4+ — that is the supported matrix as of 3.0.0. Laravel 13 support landed in this release, so the package is current with the framework's latest line.
• Your payloads map cleanly to class properties with nested types, and your team is comfortable with PHP 8 annotations/attributes and docblock type hints.
• The integration surface is small-to-medium (a handful of endpoints), your team is small, and you want the least ceremony possible — no validation pipeline, no query-string builder, no collection magic.
• You need a permissively licensed (MIT) dependency you can wrap, pin, and — if abandoned — fork with modest effort.
• You're prototyping and want to defer a heavier serialization/validation framework decision.

Look elsewhere when:

• You are pinned to Laravel 10 or below, or PHP 7.2/7.3. 3.0.0 drops those; the release notes are internally inconsistent here (see the gate below), so treat the actual constraint file as the source of truth.
• You need validation rules, casting, nested collections, pagination, or request-to-DTO handling in one tool — that is a different, more opinionated product category.
• You require PHP 8 attribute-first configuration with custom handlers and strict constructor mapping — verify the underlying library's capabilities first; the wrapper does not add them.
• The mapping layer is on a critical revenue path and your org requires maintained dependencies with multiple contributors, a security-response process, or commercial support. Zero dependents means no ecosystem pressure-testing, and the 3.0.0 major bump is itself a reminder that upgrade work will land on your team.
• You are not on Laravel, or you want a serializer shared with a non-Laravel service.
• You need streaming/large-payload performance guarantees — validate before committing.

Adoption gate: run a one-sprint spike behind an interface (PayloadMapper), pin the version, and write the swap-out test before merging. On 3.0.0 specifically, first reconcile the release notes against composer.json: the changelog simultaneously claims "restore support for Laravel 8, 9 and 10" and "dropped support for Laravel 5.5 through 10; minimum supported Laravel version is now 11." Those cannot both be true, and the answer determines whether your 10.x product lines can upgrade at all. Read the manifest, run CI against your actual framework version matrix, and record the supported floor in the ADR. If the abstraction holds, the dependency risk is contained; if it doesn't, you learned that cheaply.

How to Pitch It (Stakeholders)

For executives (one paragraph): Partner and third-party integrations are where our defect density and schedule variance concentrate, because converting untrusted JSON into our domain types is hand-written every time. This package is a small, MIT-licensed Laravel wrapper around an established JSON-to-object mapping library. Adopting it standardizes that conversion, shrinks integration code, and makes payload handling testable. The new 3.0.0 release is a maintenance release, not a feature release: it adds Laravel 13 support and modernizes the project's CI and release automation — a positive signal that the dependency is being actively kept current rather than abandoned. Its cost is the familiar one — a dependency, a config file, and roughly a sprint of spike work behind an internal interface — plus a major-version upgrade constraint: 3.x requires Laravel 11+ and PHP 7.4+, so any product still on Laravel 10 stays on the older branch. Risk stays low and bounded: the library is small, permissively licensed, forkable, and we will hide it behind our own abstraction so switching costs stay near zero. Recommendation: approve a time-boxed spike on the next integration, on a service already on Laravel 11+, not a platform-wide mandate; revisit breadth once we have defect-rate data.

For engineering (specifics): The wrapper contributes container binding and publishable configuration; the actual mapping semantics come from the underlying JsonMapper library — evaluate that, not this. It does not do validation, casting, or collections; we keep those separate. Integration plan: bind a PayloadMapper interface in our own namespace, implement it with this package, add contract tests over representative real payloads (nulls, absent keys, wrong types, deeply nested arrays), pin the exact version in composer.json, and document the swap path. On 3.0.0, two things to verify before pinning: (1) the changelog contradicts itself on Laravel 8–10 support — read composer.json and the CI matrix, do not trust the notes; (2) the release is a major bump with dropped PHP 7.2/7.3 and Laravel 5.5–10 support, so confirm every consuming app meets the new floor and that no transitive constraint forces an older wrapper — if one does, freeze that app on 2.x and track it as tech debt rather than mixing major versions across services. Success metrics for the spike: lines of mapping code deleted, mapping-related bug count on the integration, time-to-first-successful-endpoint versus the previous manual approach, and upgrade effort consumed by the major bump.