Soft Deleteable Extension Bundle Laravel Package

Technical Evaluation

First-order finding: this is not a Laravel package. Before any roadmap discussion, a TPM needs to close the stack question, because it determines whether this item consumes engineering capacity at all. The package is a Symfony bundle (Evence\Bundle\SoftDeleteableExtensionBundle) extending Gedmo's Doctrine SoftDeleteable listener for the Doctrine ORM. There is no service provider, no Eloquent hook, no Laravel package manifest. The "Laravel/PHP package" framing in the intake is a categorisation error, and the correct TPM action is portfolio triage, not backlog grooming.

What it buys the product. Gedmo soft-delete sets deletedAt instead of removing the row, which bypasses database ON DELETE semantics entirely. Associations then point at records that are logically gone, producing Doctrine EntityNotFoundException and proxy-hydration errors that surface as production incidents and inconsistent reporting. This bundle restores declarative referential actions at the ORM layer:

• CASCADE → "deleting a shop archives its listings."
• SET NULL → "unlinking is not deleting" (child record preserved).
• SUCCESSOR → "reassign to the replacement record" (merges, plan migrations, ownership transfers).

That third mode is the differentiator. It has no clean built-in equivalent, and it is the mode that retires hand-written one-off migration scripts — a recurring, unbudgeted engineering cost that a TPM can point to directly.

Integration feasibility. Low effort if the stack matches: Composer require, bundle registration, annotate the owning side of an association. No schema migration, no backfill, no new infrastructure. The real cost is verification, not implementation — the package's compatibility envelope (PHP version, Doctrine ORM 3, DBAL 4, Gedmo 3.x, attribute vs. annotation mapping) is not evidenced in the README.

Technical risk. Three concentrated areas, each with a TPM-visible consequence:

• Coupling to Gedmo internals. Extending a listener means tracking Gedmo's event signatures and UnitOfWork behaviour across upgrades. Every Gedmo bump becomes a potential regression in our delete semantics — and delete paths are rarely well covered by tests.
• Ecosystem signal. 57 stars and 0 dependents means effectively no battle-testing in the wild and no downstream projects to observe for breakage patterns. The October 2024 release is a liveness signal, not a durability signal. Treat as adopt-and-own, never adopt-and-depend.
• Semantic edge cases. Recursive cascades, cyclic associations, SUCCESSOR chains, bulk DQL deletes, and interaction with SoftDeleteableFilter are all places where "behaves like SQL ON DELETE" is an aspiration rather than a contract.

Key questions to put to engineering before committing scope.

1. Which Doctrine ORM / DBAL / Gedmo / PHP versions are supported? Is there a CI matrix, or only changelog prose?
2. Does it support PHP 8 attributes, or only docblock annotations? The README is annotation-only, and the annotation reader is removed in ORM 3 — an annotation-only answer is a hard stop.
3. Does the listener wrap cascades in a transaction, or can a partial cascade commit?
4. Is there cycle/recursion protection for CASCADE and SUCCESSOR?
5. Does it hook preSoftDelete only, or also bulk DQL DELETE and programmatic remove()?
6. Which association types are covered — ManyToOne only, or OneToOne / ManyToMany too?
7. Is there a named maintainer with commit rights, or is this effectively a single-maintainer archive?

Integration Approach

Stack fit is the gate, not a variable. Pursue only where Doctrine + Gedmo are already load-bearing. If a Laravel team is considering introducing Doctrine solely to gain this behaviour, reject: the correct Laravel answer is deleting/deleted model events or a service that enforces cascade semantics explicitly. Framing this correctly saves a TPM from sponsoring an architecture change disguised as a library adoption.

Migration path. Incremental, additive, and reversible — the strongest selling point for stakeholder conversations:

• No database DDL, no backfill, no deployment choreography.
• Work is: pinned composer require → bundle registration → annotate one relation → characterise behaviour with tests → widen.
• Rollback is annotation removal plus a revert; blast radius stays inside one module during the pilot.

Compatibility — fork-first. Given 0 dependents and a narrow maintainer base, the recommended posture is to vendor the source into the monorepo or hold a private fork under our own CI matrix. This converts an availability risk into a known, low-cost maintenance line and preserves the right to patch Doctrine/Gedmo compatibility ourselves. MIT permits this cleanly (attribute and preserve the notice — confirm with legal, but there should be no blocker).

Sequencing.

1. Spike (1–2 days, one engineer). Install in a branch, reproduce one real orphaned-reference failure, confirm the fix. Success criterion is a failing test that now passes — not a demo.
2. Compatibility gate (0.5 day). Pin PHP / ORM / DBAL / Gedmo. Verify attribute mapping. Kill criterion: annotations-only or no ORM 3 support → stop here and take the fallback.
3. Pilot in one non-critical module (3–5 days incl. tests). Prefer a module with a genuine parent→child soft-delete relationship but no money path.
4. Policy capture. For each pilot relationship, record the chosen mode in the product spec/decision log. The package makes retention policy explicit; the TPM's deliverable here is the policy, not the code.
5. Widen or fork. If the pilot holds, vendor the source and roll out per-domain as features require it.
6. Fallback (1–3 days). Internal listener implementing the same three behaviours. This is a genuinely acceptable outcome — the package's residual value is that it has already specified the semantics for us, so the spec is free either way.

Sequencing rationale for stakeholders: steps 1–2 are timeboxed to under three engineer-days, which keeps the option value high and the downside bounded.

Operational Impact

Maintenance. The dominant ongoing cost is not the package, it is the Gedmo compatibility surface. Budget a recurring, low-frequency task: on every Doctrine/Gedmo upgrade, re-run the delete-path test suite against the vendored copy. If we vendor, this becomes a normal internal dependency review; if we depend on Packagist, it becomes an unowned risk with no upstream SLA. Recommend vendoring, assigned to the owning team, reviewed at each major ORM bump.

Support. There is no vendor support, no SLA, and a single-maintainer profile. The TPM must name an internal owner before adoption — "the platform team will handle it" is not an owner. Escalation path is: patch our fork. That requires at least one engineer comfortable in Doctrine event listeners and UnitOfWork, which is a hiring/training consideration, not just a scheduling one.

Scaling. Watch three things as data volume grows: deep CASCADE trees (soft-deleting a high-fan-out parent can touch many rows in one request — a latency and lock-duration concern), SUCCESSOR chains during large account/plan migrations (verify idempotency and re-run safety), and bulk operations. Soft delete does not shrink tables; retention and purge jobs remain a separate, unaddressed obligation. Do not let "we do soft deletes" become a substitute for a retention policy.

Failure modes to monitor and test for.

• Partial cascade commits — parent soft-deleted, some children not. Highest-severity failure; requires a transaction-boundary test.
• Silent divergence — a new association added without an onSoftDelete annotation reintroduces orphaned references with no compile-time warning. Mitigate with a convention check in CI or a code-review checklist item.
• Cycles and recursion — CASCADE loops or SUCCESSOR cycles hanging or corrupting the delete path.
• Filter interaction — deleted children hidden from queries while still referenced, producing confusing 404s that look like data loss to support teams.
• Divergence from SQL semantics — behaviour differs from the ON DELETE mental model engineers assume, especially for bulk DQL.

Ramp-up. Small API surface (three modes, one annotation) — a developer is productive in well under a day. The real ramp-up is conceptual: understanding Doctrine association ownership, Gedmo listener timing, and why soft delete breaks ON DELETE in the first place. Budget onboarding material as a short internal note covering the three modes, the cycle/transaction caveats, and the "annotate every owning association" rule. Support and QA also need the mental model — otherwise "the record still exists but is invisible" generates tickets that look like bugs.

Bottom line for the roadmap. Adopt where Symfony + Doctrine + Gedmo already hold; reject outright on Eloquent. Bound the exposure with a timeboxed spike, a fork-first posture, and a named internal owner. The value is not the 57-star library — it is the explicit, reviewable per-relationship retention policy that adopting it forces the team to write down.