From 30e599b94fbe79bd7bbec29a26987bb0ae4e2a0a Mon Sep 17 00:00:00 2001
From: Carsten Brandt <mail@cebe.cc>
Date: Tue, 27 Dec 2016 21:34:36 +0100
Subject: [PATCH] updated docs about deleteALl() and updateAll()

---
 framework/db/ActiveRecord.php | 38 +++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/framework/db/ActiveRecord.php b/framework/db/ActiveRecord.php
index 06c67c4b94..73067c763a 100644
--- a/framework/db/ActiveRecord.php
+++ b/framework/db/ActiveRecord.php
@@ -190,12 +190,29 @@ class ActiveRecord extends BaseActiveRecord
 
     /**
      * Updates the whole table using the provided attribute values and conditions.
+     *
      * For example, to change the status to be 1 for all customers whose status is 2:
      *
      * ```php
      * Customer::updateAll(['status' => 1], 'status = 2');
      * ```
      *
+     * > Warning: If you do not specify any condition, this method will update **all** rows in the table.
+     *
+     * Note that this method will not trigger any events. If you need [[EVENT_BEFORE_UPDATE]] or
+     * [[EVENT_AFTER_UPDATE]] to be triggered, you need to [[find()|find]] the models first and then
+     * call [[update()]] on each of them. For example an equivalent of the example above would be:
+     *
+     * ```php
+     * $models = Customer::find()->where('status = 2')->all();
+     * foreach($models as $model) {
+     *     $model->status = 1;
+     *     $model->update(false); // skipping validation as no user input is involved
+     * }
+     * ```
+     *
+     * For a large set of models you might consider using [[ActiveQuery::each()]] to keep memory usage within limits.
+     *
      * @param array $attributes attribute values (name-value pairs) to be saved into the table
      * @param string|array $condition the conditions that will be put in the WHERE part of the UPDATE SQL.
      * Please refer to [[Query::where()]] on how to specify this parameter.
@@ -212,12 +229,15 @@ class ActiveRecord extends BaseActiveRecord
 
     /**
      * Updates the whole table using the provided counter changes and conditions.
+     *
      * For example, to increment all customers' age by 1,
      *
      * ```php
      * Customer::updateAllCounters(['age' => 1]);
      * ```
      *
+     * Note that this method will not trigger any events.
+     *
      * @param array $counters the counters to be updated (attribute name => increment value).
      * Use negative values if you want to decrement the counters.
      * @param string|array $condition the conditions that will be put in the WHERE part of the UPDATE SQL.
@@ -241,7 +261,6 @@ class ActiveRecord extends BaseActiveRecord
 
     /**
      * Deletes rows in the table using the provided conditions.
-     * WARNING: If you do not specify any condition, this method will delete ALL rows in the table.
      *
      * For example, to delete all customers whose status is 3:
      *
@@ -249,6 +268,21 @@ class ActiveRecord extends BaseActiveRecord
      * Customer::deleteAll('status = 3');
      * ```
      *
+     * > Warning: If you do not specify any condition, this method will delete **all** rows in the table.
+     *
+     * Note that this method will not trigger any events. If you need [[EVENT_BEFORE_DELETE]] or
+     * [[EVENT_AFTER_DELETE]] to be triggered, you need to [[find()|find]] the models first and then
+     * call [[delete()]] on each of them. For example an equivalent of the example above would be:
+     *
+     * ```php
+     * $models = Customer::find()->where('status = 3')->all();
+     * foreach($models as $model) {
+     *     $model->delete();
+     * }
+     * ```
+     *
+     * For a large set of models you might consider using [[ActiveQuery::each()]] to keep memory usage within limits.
+     *
      * @param string|array $condition the conditions that will be put in the WHERE part of the DELETE SQL.
      * Please refer to [[Query::where()]] on how to specify this parameter.
      * @param array $params the parameters (name => value) to be bound to the query.
@@ -643,7 +677,7 @@ class ActiveRecord extends BaseActiveRecord
     }
 
     /**
-     * Returns a value indicating whether the specified operation is transactional in the current [[scenario]].
+     * Returns a value indicating whether the specified operation is transactional in the current [[$scenario]].
      * @param int $operation the operation to check. Possible values are [[OP_INSERT]], [[OP_UPDATE]] and [[OP_DELETE]].
      * @return bool whether the specified operation is transactional in the current [[scenario]].
      */