Product Decisions This Supports
- Build vs. buy on the serialization layer. Hand-rolled transformers, per-endpoint
toArray() overrides and ad-hoc JsonResource chains are a recurring tax. This package replaces them with one declarative mapping layer — directly relevant to any "reduce bespoke glue code" or platform-consolidation initiative.
- Multi-format API surface (JSON + XML). If the roadmap includes XML at all — partner integrations, legacy/SOAP-adjacent feeds, industry schemas (e-invoicing, travel, publishing), sitemaps, data exports — this collapses a "build a second output layer" epic into configuration.
- API versioning and deprecation cadence. Declarative versioning lets one model serve v1 and v2 simultaneously, decoupling the "keep the old version alive for N months" commitment from internal refactors. This is the single strongest product lever here.
- Public API contract as a reviewable artifact. Mapping config lives in the repo, diffs in PRs, and can be asserted in contract tests — better governance than payload shape emerging implicitly from controller code.
- Rich or relational domain graphs. Circular references, lazy-loaded relations, per-audience field sets (admin vs. public vs. internal), and conditional exclusion are the cases where default framework serialization degrades into special-casing.
- Inbound payload handling. Deserialization with type inference,
DateTimeInterface handling, custom handlers and Doctrine object construction supports webhook ingestion, partner imports, and PATCH-style writes — not just responses.
- Data export and reporting pipelines. Serializing entity graphs to JSON/XML for downstream consumers, audit snapshots, or ETL extracts.
When to Consider This Package
Adopt when:
- You must emit or consume more than one format, with XML as a real near-term requirement rather than a hypothetical.
- The public API is versioned and versioning must be expressed declaratively instead of duplicating controllers or resources.
- Serialization rules vary by audience or feature flag, and you want that logic at the mapping layer rather than scattered through controllers.
- Payload shape is a contract with external partners, where stability and reviewability matter more than minimal code.
- Domain models are deeply nested or Doctrine-managed, where circular-reference and proxy handling is otherwise a bug farm.
Look elsewhere or deprioritize when:
- The app is a straightforward Laravel JSON API over Eloquent.
JsonResource / toArray is idiomatic, zero-config, and adding a second mapping layer is pure overhead.
- The team already standardizes on Symfony Serializer or API Platform. Running two serializers is a maintenance tax with no product upside.
- No one will own the configuration surface. XML/YAML drivers and annotation heritage are powerful but need a named owner and conventions, or they rot.
- Hot paths with trivial payloads. Reflection and metadata lookups need a warmed cache to be competitive; a hand-written mapper wins on small fixed shapes.
- Anyone proposes the 1.x or 2.x branches. They are end-of-life with no feature releases — do not adopt legacy lines.
Validation gates before committing:
- Confirm the PHP / Laravel / Doctrine compatibility matrix against our stack; 3.15 added Symfony 6 and DBAL 3 support, so pin deliberately.
- Decide and document the metadata cache backend. The project moved off
doctrine/cache to PSR-6/PSR-16, so this is an operational choice we now own (filesystem adapter, Redis, etc.).
- Benchmark cold vs. warm serialization on a representative payload, including cache warm-up in the deploy step.
- Treat the "0 dependents" figure in this dataset as a data artifact, not a signal — sanity-check real-world adoption on Packagist and GitHub before using it as either a risk or a safety argument.
- Budget for maintenance reality: active 3.x line, steady but incremental releases skewed toward compatibility and bugfixes, single-maintainer-led, with an explicit paid-support channel. Fine for most uses; budget for it if XML edge cases become load-bearing.
How to Pitch It (Stakeholders)
Executives. This is a mature, MIT-licensed, widely used PHP library that turns domain objects into JSON and XML and back, driven by configuration instead of custom code. The business case is delivery speed on multi-format and versioned API work: one mapping layer serves every endpoint and every format, so new partner formats and API versions ship as configuration rather than as new code and new tests. Licensing risk is negligible, integration risk is contained to a single library, and the migration can be scoped to one endpoint as a spike. The genuine risk is maintenance concentration — it is a single-maintainer-led open source project with paid support available — so the recommendation is a timeboxed pilot on one real, XML-or-versioning-dependent endpoint before any broader commitment.
Engineering. You get declarative mapping via XML, YAML or PHP attributes, plus visitor and handler extension points, groups, versioning, conditional exclusion, Doctrine object construction, and first-class JSON and XML visitors. PHP 8 attributes are enabled by default since 3.14, and caching now uses PSR-6/PSR-16, so it fits a modern stack without dragging in abandoned dependencies. The cost is a second metadata layer to learn and operate, plus cache warm-up in the deploy path. Mitigate with a single named owner, documented mapping conventions, and serialization tests treated as contract tests. Where we are JSON-only on Eloquent, JSON Resources remain the correct default — bring this in specifically where XML, versioning, or complex object graphs actually hurt.