From f43640e0d252653b9071e0e357e5ed453bef49b0 Mon Sep 17 00:00:00 2001
From: Michael Hoffmann <mh@scherer-software.de>
Date: Thu, 16 Feb 2017 23:25:29 +0100
Subject: [PATCH 1/2] Add docs for saveOrFail and deleteOrFail

---
 en/development/errors.rst |  7 +++++++
 en/orm/deleting-data.rst  | 23 +++++++++++++++++++++++
 en/orm/saving-data.rst    | 25 +++++++++++++++++++++++++
 3 files changed, 55 insertions(+)

diff --git a/en/development/errors.rst b/en/development/errors.rst
index ed6adb244c..7c4e35331c 100644
--- a/en/development/errors.rst
+++ b/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
diff --git a/en/orm/deleting-data.rst b/en/orm/deleting-data.rst
index 090cd88e48..e5559ddfd7 100644
--- a/en/orm/deleting-data.rst
+++ b/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
\ No newline at end of file
diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst
index 856a90343e..303ff4a03b 100644
--- a/en/orm/saving-data.rst
+++ b/en/orm/saving-data.rst
@@ -1106,6 +1106,31 @@ 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.
+
+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
 ========================
 

From 62d9be9b6af82a552aa8371119b77997157d36e7 Mon Sep 17 00:00:00 2001
From: Michael Hoffmann <mh@scherer-software.de>
Date: Thu, 16 Feb 2017 23:47:27 +0100
Subject: [PATCH 2/2] Add hint for not using this method in certain cases

---
 en/orm/saving-data.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/en/orm/saving-data.rst b/en/orm/saving-data.rst
index 303ff4a03b..2882d1aac4 100644
--- a/en/orm/saving-data.rst
+++ b/en/orm/saving-data.rst
@@ -1117,6 +1117,11 @@ if the application rules checks failed, the entity contains errors or the save w
 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::