Entity Resource Mapper Bundle Laravel Package

Product Decisions This Supports

• API contract vs. persistence model decoupling. Decides whether your public API resources are the same objects as your database entities or separate, purpose-built representations. This package takes the "separate" position: map Doctrine entities to API Platform resources so schema migrations, denormalized columns, and internal fields never leak into the public contract.
• Roadmap sequencing for a headless/public API. If v2 of a product includes opening the API to partners or third parties, this is a "do it before the first external consumer" decision — retrofitting resource separation after clients depend on the entity shape is a breaking change with a long tail.
• Build vs. buy for the mapping layer. The choice is roughly: (a) adopt a mapper bundle, (b) use API Platform's native DTO / input-output support, (c) hand-write mappers, (d) fork/vendor a small package like this one. Buy is only rational when the bought thing is maintained; with 1 star, 0 dependents, and a last release in July 2024, the honest framing is "buy the idea, own the code."
• Team cognitive load budget. A mapper adds an indirection layer every engineer must learn. Worth it on a multi-consumer API with a schema that changes often; actively harmful on a single-team, single-client CRUD app.
• Use cases where the pattern pays off: versioned public APIs, multi-tenant APIs where the same entity surfaces differently per tenant, mobile clients that need aggregated/reshaped payloads, APIs fronting legacy schemas you cannot change, and read models for reporting endpoints.
• Framework-fit decision. Note this is a Symfony / API Platform bundle, not a Laravel package, despite the brief. For a Laravel codebase the equivalent capability already exists natively in Eloquent API Resources and in packages like Fractal or Spatie Laravel Data — so the strategic decision for a Laravel shop is "we need this pattern," not "we need this package."

When to Consider This Package

Consider the pattern — and only this concrete package as a reference implementation — when:

• You run API Platform on Symfony with Doctrine entities and want resource classes separate from entities without hand-writing every hydrator.
• Your entities carry internal fields (soft-delete flags, audit columns, billing state, PII) that must never appear in API responses, and you want that guarantee enforced structurally rather than by serialization-group discipline.
• You expect the API schema to change frequently relative to the database schema, or vice versa.
• You want a small, MIT-licensed, readable codebase you are comfortable reading end-to-end and vendoring into your own repo.

Look elsewhere when:

• You are on Laravel. API Platform is a Symfony-first ecosystem. Laravel's Eloquent API Resources solve the same problem natively; adding a Symfony bundle to a Laravel app is a dead end. Use Laravel API Resources, Spatie Laravel Data, or Fractal.
• You need vendor support, SLAs, or a security response path. One star, zero dependents, and a single-maintainer release cadence mean no support contract and no downstream pressure-testing. A CVE or an API Platform major-version bump may go unaddressed indefinitely.
• The team is small and the API is internal-only. The indirection cost exceeds the coupling risk.
• API Platform's built-in DTO / input-output support already covers your case. Reach for the framework primitive before a third-party bundle; it is maintained, documented, and on the upgrade path.
• You cannot own the code. If adopting means "we depend on this staying alive," say no. If adopting means "we copy it into src/ and maintain it," it is a defensible starting point.

How to Pitch It (Stakeholders)

For executives (one paragraph): We evaluated a small open-source component that keeps our database model and our public API shape from becoming the same thing. The underlying idea is sound and is standard practice for any API we intend to expose to customers or partners — it prevents internal data (billing fields, audit columns, flags) from leaking into responses and stops routine database changes from becoming breaking API changes. However, this specific package is a one-maintainer, one-star Symfony component with no adoption, no support, and no upgrade guarantee; it is not a dependency we should take on. Our recommendation is to adopt the pattern using tooling we already control — Laravel's native API Resources if we are on Laravel, or API Platform's built-in DTO support if we are on Symfony — and revisit this package only as a design reference, not as a dependency.

For engineering: Treat the repo as a readable, MIT-licensed worked example of entity↔resource mapping for API Platform, not as a package to composer require. With zero dependents and a single release in 2024, we would be the only production user — meaning we find the bugs and we carry the upgrade work across API Platform majors. If the mapping layer is genuinely needed, implement it on framework primitives or vendor ~a few hundred lines into our own namespace with tests and ownership. Decision needed now: confirm whether our API consumers are external in the next two quarters. If yes, resource separation belongs in the architecture before the first external contract ships, because it is cheap today and a breaking change later. If our API stays internal, defer.