shiftonelabs / laravel-cascade-deletes
Adds application level cascading deletes to Eloquent Models.
Installs: 311 453
Dependents: 2
Suggesters: 0
Security: 0
Stars: 155
Watchers: 6
Forks: 12
Open Issues: 0
Requires
- php: >=8.0.2
- illuminate/database: >=9.0
- illuminate/events: >=9.0
Requires (Dev)
- mockery/mockery: ~1.3
- phpunit/phpunit: ~9.3 || ~10.0
- shiftonelabs/codesniffer-standard: 0.*
- squizlabs/php_codesniffer: 3.*
This package is auto-updated.
Last update: 2024-10-22 15:50:15 UTC
README
This Laravel/Lumen package provides application level cascading deletes for the Laravel's Eloquent ORM. When referential integrity is not, or cannot be, enforced at the data storage level, this package makes it easy to set this up at the application level.
For example, if you are using SoftDeletes
, or are using polymorphic relationships, these are situations where foreign keys in the database cannot enforce referential integrity, and the application needs to step in. This package can help.
Versions
This package has been tested on Laravel 4.1 through Laravel 11.x, though it may continue to work on later versions as they are released. This section will be updated to reflect the versions on which the package has actually been tested.
This readme has been updated to show information for the most currently supported versions (9.x - 11.x). For Laravel 4.1 through Laravel 8.x, view the 1.x branch.
Install
Via Composer
composer require shiftonelabs/laravel-cascade-deletes
Usage
Enabling cascading deletes can be done two ways. Either:
- update your
Model
to extend the\ShiftOneLabs\LaravelCascadeDeletes\CascadesDeletesModel
, or - update your
Model
to use the\ShiftOneLabs\LaravelCascadeDeletes\CascadesDeletes
trait.
Once that is done, define the $cascadeDeletes
property on the Model
. The $cascadeDeletes
property should be set to an array of the relationships that should be deleted when a parent record is deleted.
Now, when a parent record is deleted, the defined child records will also be deleted. Furthermore, in the case where a child record also has cascading deletes defined, the delete will cascade down and delete the related records of the child, as well. This will continue on until all children, grandchildren, great grandchildren, etc. are deleted.
Additionally, all cascading deletes are performed within a transaction. This makes the delete an "all or nothing" event. If, for any reason, a child record could not be deleted, the transaction will rollback and no records will be deleted at all. The Exception
that caused the child not to be deleted will bubble up to where the delete()
originally started, and will need to be caught and handled.**
Code Example
User Model:
<?php namespace App; use Illuminate\Database\Eloquent\Model; use ShiftOneLabs\LaravelCascadeDeletes\CascadesDeletes; class User extends Model { use CascadesDeletes; protected $cascadeDeletes = ['posts', 'profile']; public function posts() { return $this->hasMany(Post::class); } public function profile() { return $this->hasOne(Profile::class); } public function type() { return $this->belongsTo(Type::class); } }
Profile Model:
<?php namespace App; use Illuminate\Database\Eloquent\Model; use ShiftOneLabs\LaravelCascadeDeletes\CascadesDeletes; class Profile extends Model { use CascadesDeletes; protected $cascadeDeletes = ['addresses']; public function user() { return $this->belongsTo(User::class); } public function addresses() { return $this->morphMany(Address::class, 'addressable'); } }
In the example above, the CascadesDeletes
trait has been added to the User
model to enable cascading deletes. Since the user is considered a parent of posts and profiles, these relationships have been added to the $cascadeDeletes
property. Additionally, the Profile
model has been set up to delete its related address records.
Given this setup, when a user record is deleted, all related posts and profile records will be deleted. The delete will also cascade down into the profile record, and it will delete all the addresses related to the profile, as well.
If any one of the posts, profiles, or addresses fails to be deleted, the transaction will roll back and no records will be deleted, including the original user record.**
** Transaction rollback will only occur if the database being used actually supports transactions. Most do, but some do not. For example, the MySQL InnoDB
engine supports transactions, but the MySQL MyISAM
engine does not.
SoftDeletes
This package also works with Models that are setup with SoftDeletes
.
When using SoftDeletes
, the delete method being used will cascade to the rest of the deletes, as well. That is, if you delete()
a record, all the child records will also use delete()
; if you forceDelete()
a record, all the child records will also use forceDelete()
.
The deletes will also cross the boundary between soft deletes and hard deletes. In the code example above, the the User
record was setup to soft delete, but the Profile
record was not, then when a user is deleted, the User
record would be soft deleted, but the child Profile
record would be hard deleted, and vice versa.
Notes
-
The functionality in this package is provided through the
deleting
event on theModel
. Therefore, in order for the cascading deletes to work,delete()
must be called on a model instance. Deletes will not cascade if a delete is performed through the query builder. For example,App\User::where('active', 0)->delete();
will only delete those user records, and will not perform any cascading deletes, since thedelete()
was performed on the query builder and not on a model instance. -
Do not add a
BelongsTo
relationship to the$cascadeDeletes
array. This will cause aLogicException
, and no records will be deleted. This is done as aBelongsTo
typically represents a child record, and it usually does not make sense to delete a parent record from a child record.
Contributing
Contributions are welcome. Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email patrick@shiftonelabs.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.