Add docs for saveOrFail and deleteOrFail

en/development/errors.rst

@@ -323,6 +323,13 @@ be thrown from a number of CakePHP core components:
 
     A model's behavior could not be found.
 
+.. php:exception:: PersistenceFailedException
+
+    An entity couldn't be saved/deleted while using :php:meth:`Cake\\ORM\\Table::saveOrFail()` or
+    :php:meth:`Cake\\ORM\\Table::deleteOrFail()`.
+
+    .. versionadded:: 3.4.1 PersistenceFailedException has been added.
+
 .. php:namespace:: Cake\Datasource\Exception
 
 .. php:exception:: RecordNotFoundException

en/orm/deleting-data.rst

@@ -76,3 +76,26 @@ A bulk-delete will be considered successful if 1 or more rows are deleted.
 
     deleteAll will *not* trigger beforeDelete/afterDelete events. If you need those
     first load a collection of records and delete them.
+
+Strict Deletes
+--------------
+
+.. php:method:: deleteOrFail($entity, $options = [])
+
+
+Using this method will throw an :php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException`
+if the entity is new, has no primary key value, application rules checks failed
+or the delete was aborted by a callback.
+
+If you want to track down the entity that failed to save, you can use the
+:php:meth:`Cake\\ORM\Exception\\PersistenceFailedException::getEntity()` method::
+
+        try {
+            $table->deleteOrFail($entity);
+        } catch (\Cake\ORM\Exception\PersistenceFailedException $e) {
+            echo $e->getEntity();
+        }
+
+As this internally perfoms a :php:meth:`Cake\\ORM\\Table::delete()` call, all corresponding delete events will be triggered.
+
+.. versionadded:: 3.4.1

en/orm/saving-data.rst

@@ -1106,6 +1106,36 @@ receiving from the end user is the correct type. Failing to correctly handle
 complex data could result in malicious users being able to store data they
 would not normally be able to.
 
+Strict Saving
+=============
+
+.. php:method:: saveOrFail($entity, $options = [])
+
+
+Using this method will throw an :php:exc:`Cake\\ORM\\Exception\\PersistenceFailedException`
+if the application rules checks failed, the entity contains errors or the save was aborted by a callback.
+Using this can be helpful when you performing complex database operations without human monitoring,
+for example, inside a Shell task.
+
+.. warning::
+
+    Do not use this method when the save was triggered by a user, for example,
+    within a controller action or if you want to give a user feedback within a form.
+
+If you want to track down the entity that failed to save, you can use the
+:php:meth:`Cake\\ORM\Exception\\PersistenceFailedException::getEntity()` method::
+
+        try {
+            $table->saveOrFail($entity);
+        } catch (\Cake\ORM\Exception\PersistenceFailedException $e) {
+            echo $e->getEntity();
+        }
+
+As this internally perfoms a :php:meth:`Cake\\ORM\\Table::save()` call, all corresponding save events
+will be triggered.
+
+.. versionadded:: 3.4.1
+
 Saving Multiple Entities
 ========================