Download the PHP package gigerit/laravel-cascade-delete without Composer

Laravel Cascade Delete

Smart cascading deletes for Laravel Eloquent with support for soft deletes, polymorphic relations, and automatic detaching.

The main advantage of this package over others is its unified approach. While many packages handle only soft deletes or only standard relations, this package provides a single trait that intelligently manages all variants:

• Standard Relations (HasOne, HasMany)
• Soft Deletes (Recursive soft/hard deletion)
• Polymorphic Relations (MorphOne, MorphMany)
• Many-to-Many Relations (BelongsToMany, MorphToMany) via automatic detaching
• Orphan Cleanup: Tools to clean residual polymorphic records after bulk deletions

Features

• All-in-One Trait: Handles all relationship types in a single implementation.
• Transaction Safety: All cascading operations are wrapped in a database transaction to ensure atomicity.
• Integrity Verification: Verifies that the number of deleted or detached records matches expectations.
• Intelligent Detaching: Automatically calls detach() for many-to-many relations instead of deleting the related models.
• Recursive Force Deleting: Correctly handles forceDelete() by propagating it to related models, even those using soft deletes.

Requirements

• PHP 8.2 or higher
• Laravel 11.x or higher

Installation

You can install the package via composer:

Usage

Simply add the CascadeDeletes trait to your model and define the $cascadeDeletes property:

How it works

• Delete / Soft Delete: When you call $model->delete(), the package will iterate through the defined relations. If the child models support soft deletes, they will be soft deleted. If not, they will be hard deleted.
• Force Delete: If you call $model->forceDelete(), the package will automatically use withTrashed() on the relations to find and permanently delete all related records.
• Many-to-Many: For BelongsToMany or MorphToMany relations, the package will call detach() on the relationship, ensuring the pivot records are removed without deleting the actual related models.
• Transactions: If any deletion fails or the record count doesn't match, the entire operation is rolled back.

Handling Orphan Polymorphic Relations

Bulk deletes in Laravel (e.g., User::where('active', false)->delete()) do not fire model events, which can leave orphaned records in polymorphic relationships. This package provides tools to identify and clean these up.

Artisan Command

You can clean up all orphaned polymorphic relations defined in your models:

Use the --dry-run flag to see how many records would be deleted without actually removing them:

Manual Cleanup

You can also trigger cleanup for a specific model class:

Configuration

You can publish the config file to customize where the package searches for models:

The default configuration looks for models in app/:

Directory names are excluded at any depth. Directory paths are relative to each configured model path. Add other non-runtime directories to models_excluded_directories when needed.

Model discovery still loads every PHP file outside the excluded directories, so keep models_paths as narrow as possible.

Handling Failures

If the number of records deleted or detached does not exactly match the number of records found in the relationship, a \LogicException will be thrown, and the database transaction will be rolled back.

This prevents silent failures where some related records might have been left orphaned due to database constraints or other issues.

Testing

Credits

• gigerit
• All Contributors

License

The MIT License (MIT). Please see License File for more information.