🌊 Laravel Cascading Soft Deletes

Automatically cascade soft-deletes and restores across your Eloquent relationships — safely, precisely, and with full multi-parent support.

✨ Why this package?

Laravel's built-in SoftDeletes trait only soft-deletes the model you call delete() on. Child models in HasOne, HasMany, or BelongsToMany relationships are left untouched — leading to orphaned records, broken UI states, and restore operations that silently bring back incomplete data.

Laravel Cascading Soft Deletes solves all of that:

📋 Requirements

🚀 Installation

1. Install via Composer

2. Run Migrations

The package includes a migration that creates the cascade_deletions tracking table. Run it with:

The migration is loaded automatically — no need to publish it unless you want to customise the schema.

3. (Optional) Publish the Config File

This copies config/cascading-soft-deletes.php into your application for customisation.

4. (Optional) Publish the Migration

If you prefer to manage the migration yourself (e.g., to rename the table):

⚙️ Basic Setup

Step 1 — Add SoftDeletes and CascadesSoftDeletes to your model

Step 2 — That's it!

🔗 Relationship Support

HasOne and HasMany

These are the primary cascadeable relationships. When the parent is deleted, all related children are soft-deleted. When the parent is restored, only children that were cascade-deleted (not independently deleted) are restored.

Nested (Deep) Relationships

Use dot-notation to cascade through multiple levels:

When User is deleted:

• User is soft-deleted
• Post records are soft-deleted
• Comment records under each post are soft-deleted

When User is restored, the full chain is restored in reverse.

BelongsToMany (Many-to-Many)

Pivot records are detached (removed from the pivot table) when a parent is soft-deleted. Since pivot data is permanently lost, re-attaching on restore is not supported.

To keep pivot records on delete, set detach_belongs_to_many => false in the config or set protected $cascadeDetachBelongsToMany = false on the model.

🔄 Smart Restore Behaviour

The restore system uses a database tracking table (cascade_deletions) — not timestamp comparisons — to decide which children to restore. This makes it:

• Precise: A child deleted independently before the parent's cascade will never be restored by the parent's restore.
• Multi-parent safe: If two parents both cascade-deleted a shared child, that child will only be restored once both parents are restored.
• Stale-safe: If a child was force-deleted or independently restored after the cascade, stale tracking records are cleaned up automatically.

Example: Independent Deletion Not Restored

Example: Multi-Parent Guard

⚙️ Configuration Reference

After publishing, edit config/cascading-soft-deletes.php:

🎛️ Per-Model Configuration

Every config option can be overridden on a per-model basis using protected properties. Model-level settings always take precedence over the global config.

Using a Method Instead of a Property

For dynamic relationship lists, you may implement cascadeRelationships() as a method:

🔢 Nesting Limit

The default maximum nesting depth is 3 levels (e.g. user → post → comment → reply). You can configure this globally or per-model.

If a relationship path exceeds the limit, a NestingLimitExceededException is thrown at delete time:

💥 Force Delete Cascade

When a model is force-deleted, the cascade hard-deletes all children (using forceDelete() if available, otherwise delete()). All tracking records are purged:

🗃️ The CascadeDeletion Model

The cascade_deletions table is exposed as a first-class Eloquent model for inspection or debugging:

Each record contains:

🛡️ Error Handling

Throwing exceptions (default)

By default (throw_on_error = true), any exception during cascading is logged and re-thrown, allowing your application to handle it:

Suppressing exceptions

Set throw_on_error = false (globally or per-model) to silently log errors via Laravel's Log::error() without interrupting execution:

Transaction rollback

When use_transaction = true and rollback_on_error = true (both default), any error during cascading will roll back the entire delete operation — keeping your database consistent:

🧪 Testing

The test suite covers:

• Basic cascade soft-delete and restore (HasOne, HasMany, nested)
• Tracking record creation and cleanup
• Independent deletion not restored
• Multi-parent cascade guard
• BelongsToMany detach and config flags
• Force delete cascade and tracking cleanup
• String/UUID primary keys
• Custom nesting limits
• Exception handling and transaction rollback

📦 Package Structure

📄 License

MIT © Krishnaraj