Laravel Record Merge Laravel Package

Product Decisions This Supports

• Duplicate-record consolidation as a first-class feature. laravel-record-merge targets the recurring "we have three copies of the same customer/company/contact" problem. This release doesn't add capability, but it makes the package's eventing contract trustworthy — which is the part a PM actually depends on for user-facing behaviour.
• Build vs. buy for merge workflows. Custom merge logic is deceptively expensive: field-level conflict resolution, relation re-parenting, soft-delete/restore semantics, and post-merge side effects. Adopting a package here keeps 1–3 sprints of engineering out of the roadmap, leaving room for the parts users see (merge preview UI, survivor selection, undo).
• Failure-path observability (newly relevant in 0.2.1). The fix — fail() renamed to failed() so the failure event actually fires — means that before this version, a failed merge could pass silently with no event emitted. Any roadmap item depending on "notify support when a merge fails," retry queues, or audit logging was previously unbuildable on 0.2.0. As of 0.2.1 it is, so those stories can be scoped and estimated rather than deferred.
• Audit, compliance, and reversibility requirements. Merge is destructive by nature. Event hooks (success and failure) are the seam where you attach audit trails, "who merged what into what," and rollback/undo. Until 0.2.1 only half of that seam existed in practice.
• Upgrade hygiene as a decision input. The fail() → failed() rename shipped in a patch release (0.2.1). For a pre-1.0 package that's defensible, but it means any internal listener, subclass, or test double calling fail() will break on upgrade. Treat "we must pin ≥0.2.1 and audit our listeners" as an explicit adoption task, not an afterthought.

When to Consider This Package

Adopt when:

• The product has genuine entity deduplication needs (CRM contacts, companies, accounts, imported lists) and you need it in weeks, not quarters.
• Your team is standard Laravel/PHP with Eloquent models and conventional event/listener patterns — the integration cost is low.
• You need merge mechanics (re-parenting relations, resolving field conflicts) but intend to own the product experience (review UI, merge rules, survivor logic) yourselves.
• You can pin the dependency and absorb pre-1.0 churn: require >=0.2.1 specifically, since earlier 0.2.x releases will not fire failure events.

Look elsewhere or build in-house when:

• You need regulated audit guarantees, legal hold, or formal data-lineage proofs — a 0.x community package should not be the sole control.
• Merge must be transactional across services/databases, or you're not on Eloquent.
• You need a ready-made admin UI or bulk/automated dedupe scoring — this is a mechanism, not a product surface.
• Single-maintainer bus factor is unacceptable for a tier-1 data-integrity path. Mitigation: wrap calls behind your own service class so the package is replaceable.
• You cannot tolerate patch-level method renames. The 0.2.1 change is small but real; if your release process can't absorb that, wait for 1.0.

How to Pitch It (Stakeholders)

To executives: Duplicate records cost sales and support real time and make reporting unreliable. Rather than fund a bespoke merge engine, we can adopt a small Laravel package that handles the hard part (moving relationships and resolving conflicting fields) and spend our effort on the visible experience and on audit controls. The 0.2.1 release closes a gap that mattered to us — failed merges now reliably emit an event, so we can alert, log, and retry instead of discovering bad merges weeks later. Caveat to state plainly: this is pre-1.0 software from a single maintainer, so we pin the version, wrap it behind our own interface, and keep an exit path.

To engineering: Treat 0.2.1 as the floor version — on 0.2.0 the failure event never fired, so error handling and any failure-driven listeners were silently dead. The fail() → failed() rename landed in a patch release, so grep for fail( in listeners, subclasses, and tests before upgrading. Recommended posture: depend on ^0.2.1, isolate the package behind a RecordMerger-style service of our own, subscribe to both success and failure events for audit and alerting, and add integration tests covering the failure path — precisely the path that was broken until now.