Doctrine Merge Persistent Collection Bundle Laravel Package

Product Decisions This Supports

• Bulk-update and sync surfaces (PUT/PATCH with full child collections). API designs where clients submit an entire collection — line items, permissions, addresses, tags — rather than per-item diffs force the backend to hydrate a detached entity graph and re-attach it via EntityManager::merge(). This package addresses precisely the failure point in that path: Doctrine's PersistentCollection does not merge correctly by default, producing duplicated rows, stale collection contents, or orphaned children. If your roadmap includes "full-replace" update semantics on relational collections, this is the defect class you will eventually hit.
• Import / ETL / batch reconciliation. Anywhere entities are built outside the unit of work (CSV ingestion, webhook payloads, third-party API sync) and merged into a live EntityManager, collection merging is a recurring cost center. This is a roadmap-level input for scoping import features and estimating their true cost.
• Queue consumers and long-running workers. Deserialized messages arrive as detached entities; re-attaching per job turns a silent duplication bug into a data-integrity incident at volume. Relevant to any reliability or scaling commitment on async processing.
• Build vs. buy: the answer is "build, or vendor." The fixed behavior is roughly a few dozen lines of explicit collection diffing (orphanRemoval, composite keys, ordering, clear-plus-re-add semantics). The value is not novel capability — it is not rediscovering edge cases. Treat this as a reference implementation to copy, not a dependency to adopt.
• Stack strategy signal (important for a Laravel-first org). This is a Symfony bundle wrapping Doctrine ORM, not a Laravel/Eloquent package. There is no service provider, no Laravel config, no Eloquent integration. For a Laravel-first product this evaluation should be closed on packaging grounds. It becomes relevant only if a bounded context has deliberately adopted Doctrine (DDD/hexagonal, or an incremental Eloquent→Doctrine migration) — in which case the behavioral insight transfers but the bundle itself does not.
• Framework decision input. Its existence is a data point for Doctrine-vs-Eloquent scoping: it confirms that Doctrine's detached-entity merge path is a known, permanently unsolved ergonomics gap. Eloquent teams have no use for it.
• Roadmap risk register. Detached-graph merging is an unsolved-in-upstream problem. If the roadmap includes heavy import/sync surfaces on Doctrine, budget for owning this logic rather than waiting on a fix.

When to Consider This Package

Consider it only when all of the following hold:

• You are on Symfony with Doctrine ORM. This bundle is not usable from Laravel; pulling Doctrine into a Laravel app to consume it is not a proportionate decision. If the stack is Laravel + Eloquent, stop — the correct action is to close the evaluation.
• You have a concrete, reproducible collection-merge defect in production or staging: duplicate child rows after merge(), orphaned children surviving an update, or cascade-merge exceptions on nested collections. If you cannot reproduce the bug, you do not need the package.
• You are prepared to read and vendor the source. With 1 star, 0 dependents, and a single maintainer, this fails any reasonable supply-chain or bus-factor bar as a live Composer dependency. Fork it or copy the merge helper into your own service layer; keep the MIT attribution.
• You have test coverage around the affected entity graph to validate the helper against real mappings. The dangerous cases are composite keys, orphanRemoval: true, ordered collections (@OrderBy), and bidirectional associations with mappedBy/inversedBy.
• Composer constraints actually resolve: verify PHP minor, doctrine/orm major (2.14+ vs 3.x — ORM 3 changed collection and UoW semantics meaningfully), doctrine/collections, and symfony/*. Do not --ignore-platform-reqs past conflicts; that converts a dependency problem into a runtime problem.

Look elsewhere — or solve it differently — when:

• You can avoid merge() entirely. The durable fix is loading managed entities and reconciling collections explicitly against the payload. More code, but it removes a whole bug class. Prefer that pattern over patching merge().
• You are greenfield. Don't choose detached-merge as a workflow and then add a 1-star bundle to make it tolerable.
• You need maintenance guarantees — security review, CVE response, LTS alignment. There are none here; treat it as unmaintained-by-default.
• Version constraints don't match. With this few users, compatibility lag is a certainty, not a risk.
• You are Laravel-first. Zero packaging fit; the only portable artifact is the merge logic.

How to Pitch It (Stakeholders)

For executives (30 seconds): This is a tiny, MIT-licensed utility addressing a known sharp edge in Doctrine, the ORM used by Symfony applications. It is not a strategic capability, and it should not go into our dependency stack: one maintainer, essentially no users, no maintenance commitments, and it is not a Laravel package — if the question came up in that context, the answer is no. The recommendation is to copy the relevant logic into our own codebase if and when we hit the problem (legally fine under MIT). Cost: roughly a day of engineering plus tests. Benefit: it closes a class of data-duplication bugs on bulk-update and import endpoints without adding supply-chain risk. Low urgency.

For engineering leads: The problem is real and worth understanding — merging detached entity graphs with PersistentCollection children produces duplicate rows, dropped elements, or cascade exceptions, and hand-rolling the fix means rediscovering the same edge cases around orphanRemoval, composite keys, and ordered collections. This repo is a compact reference for exactly those cases, and its small surface area can be audited in an afternoon. Proposal: reproduce the failing scenario with a characterization test against our actual mappings, then either reimplement in application code (~50 lines) or fork under our namespace and own the release cadence. Also note the failure mode: bugs here don't throw, they corrupt — so the test suite, not the package, becomes the support contract. Do not add it to composer.json; do not --ignore-platform-reqs around Doctrine 3.x constraints; pin the ORM while any vendored code is in use.

Recommendation: Vendor, don't depend — and only if a Doctrine merge path actually exists in our codebase. Low priority; act when an import/sync surface on Doctrine next needs work.