Deleting Data

  • class Cake\ORM\Table
  • Cake\ORM\Table::delete(Entity $entity, $options = [])

Once you’ve loaded an entity you can delete it by calling the originatingtable’s delete method:

  1. // In a controller.
  2. $entity = $this->Articles->get(2);
  3. $result = $this->Articles->delete($entity);

When deleting entities a few things happen:

  • The delete rules will be applied. If the rulesfail, deletion will be prevented.
  • The Model.beforeDelete event is triggered. If this event is stopped, thedelete will be aborted and the event’s result will be returned.
  • The entity will be deleted.
  • All dependent associations will be deleted. If associations are being deletedas entities, additional events will be dispatched.
  • Any junction table records for BelongsToMany associations will be removed.
  • The Model.afterDelete event will be triggered.By default all deletes happen within a transaction. You can disable thetransaction with the atomic option:
  1. $result = $this->Articles->delete($entity, ['atomic' => false]);

The $options parameter supports the following options:

  • atomic Defaults to true. When true the deletion happens withina transaction.
  • checkRules Defaults to true. Check deletion rules before deletingrecords.

Cascading Deletes

When deleting entities, associated data can also be deleted. If your HasOne andHasMany associations are configured as dependent, delete operations will‘cascade’ to those entities as well. By default entities in associated tablesare removed using Cake\ORM\Table::deleteAll(). You can elect tohave the ORM load related entities, and delete them individually by setting thecascadeCallbacks option to true. A sample HasMany association with boththese options enabled would be:

  1. // In a Table's initialize method.
  2. $this->hasMany('Comments', [
  3.     'dependent' => true,
  4.     'cascadeCallbacks' => true,
  5. ]);

Note

Setting cascadeCallbacks to true, results in considerably slower deleteswhen compared to bulk deletes. The cascadeCallbacks option should only beenabled when your application has important work handled by event listeners.

Bulk Deletes

  • Cake\ORM\Table::deleteMany($entities, $options = [])

If you have an array of entities you want to delete you can use deleteMany()to delete them in a single transaction:

  1. // Get a boolean indicating success
  2. $success = $this->Articles->deleteMany($entities);
  3.  
  4. // Will throw a PersistenceFailedException if any entity cannot be deleted.
  5. $this->Articles->deleteManyOrFail($entities);

The $options for these methods are the same as delete(). Deletingrecords with these method will trigger events.

  • Cake\ORM\Table::deleteAll($conditions)

There may be times when deleting rows one by one is not efficient or useful.In these cases it is more performant to use a bulk-delete to remove many rows atonce:

  1. // Delete all the spam
  2. function destroySpam()
  3. {
  4.     return $this->deleteAll(['is_spam' => true]);
  5. }

A bulk-delete will be considered successful if 1 or more rows are deleted. Thefunction returns the number of deleted records as an integer.

Warning

deleteAll will not trigger beforeDelete/afterDelete events. If you need thosefirst load a collection of records and delete them.

Strict Deletes

  • Cake\ORM\Table::deleteOrFail($entity, $options = [])

Using this method will throw anCake\ORM\Exception\PersistenceFailedException if :

  • the entity is new
  • the entity has no primary key value
  • application rules checks failed
  • the delete was aborted by a callback.

If you want to track down the entity that failed to save, you can use theCake\ORMException\PersistenceFailedException::getEntity() method:

  1. try {
  2.     $table->deleteOrFail($entity);
  3. } catch (\Cake\ORM\Exception\PersistenceFailedException $e) {
  4.     echo $e->getEntity();
  5. }

As this internally performs a Cake\ORM\Table::delete() call, allcorresponding delete events will be triggered.