Merge pull request #6183 from cdvrooman/patch-25

docs/guide/db-active-record.md

@@ -489,7 +489,7 @@ Sometimes, two tables are related together via an intermediary table called a [j
 we can customize the [[yii\db\ActiveQuery]] object by calling its [[yii\db\ActiveQuery::via()|via()]] or
 [[yii\db\ActiveQuery::viaTable()|viaTable()]] method.
 
-For example, if table `order` and table `item` are related via junction table `order_item`,
+For example, if table `order` and table `item` are related via the junction table `order_item`,
 we can declare the `items` relation in the `Order` class like the following:
 
 ```php
@@ -529,7 +529,7 @@ class Order extends \yii\db\ActiveRecord
 Lazy and Eager Loading
 ----------------------
 
-As described earlier, when you access the related objects the first time, ActiveRecord will perform a DB query
+As described earlier, when you access the related objects for the first time, ActiveRecord will perform a DB query
 to retrieve the corresponding data and populate it into the related objects. No query will be performed
 if you access the same related objects again. We call this *lazy loading*. For example,
 
@@ -721,7 +721,7 @@ and you may also join with sub-relations. For example,
 
 ```php
 // join with multiple relations
-// find out the orders that contain books and are placed by customers who registered within the past 24 hours
+// find the orders that contain books and were placed by customers who registered within the past 24 hours
 $orders = Order::find()->innerJoinWith([
     'books',
     'customer' => function ($query) {
@@ -732,7 +732,7 @@ $orders = Order::find()->innerJoinWith([
 $orders = Order::find()->joinWith('books.author')->all();
 ```
 
-Behind the scene, Yii will first execute a JOIN SQL statement to bring back the primary models
+Behind the scenes, Yii will first execute a JOIN SQL statement to bring back the primary models
 satisfying the conditions applied to the JOIN SQL. It will then execute a query for each relation
 and populate the corresponding related records.
 
@@ -759,7 +759,7 @@ you may use [[yii\db\ActiveQuery::innerJoinWith()|innerJoinWith()]].
 Below are some more examples,
 
 ```php
-// find all orders that contain books, but do not eager loading "books".
+// find all orders that contain books, but do not eager load "books".
 $orders = Order::find()->innerJoinWith('books', false)->all();
 // which is equivalent to the above
 $orders = Order::find()->joinWith('books', false, 'INNER JOIN')->all();
@@ -782,7 +782,7 @@ In the above, the [[yii\db\ActiveRecord::hasMany()|hasMany()]] method returns an
 upon which [[yii\db\ActiveQuery::onCondition()|onCondition()]] is called
 to specify that only items whose `category_id` is 1 should be returned.
 
-When you perform query using [[yii\db\ActiveQuery::joinWith()|joinWith()]], the on-condition will be put in the ON part
+When you perform a query using [[yii\db\ActiveQuery::joinWith()|joinWith()]], the ON condition will be put in the ON part
 of the corresponding JOIN query. For example,
 
 ```php
@@ -822,14 +822,13 @@ $customer->link('orders', $order);
 ```
 
 The [[yii\db\ActiveRecord::link()|link()]] call above will set the `customer_id` of the order to be the primary key
-value of `$customer` and then call [[yii\db\ActiveRecord::save()|save()]] to save the order into database.
+value of `$customer` and then call [[yii\db\ActiveRecord::save()|save()]] to save the order into the database.
 
 
 Cross-DBMS Relations
 --------------------
 
-ActiveRecord allows to establish relationship between entities from different DBMS. For example: between relational
-database table and MongoDB collection. Such relation does not require any special code:
+ActiveRecord allows you to establish relationships between entities from different DBMS. For example: between a relational database table and MongoDB collection. Such a relation does not require any special code:
 
 ```php
 // Relational database Active Record
@@ -880,10 +879,9 @@ You may call additional query methods, such as [[yii\db\ActiveQuery::where()|whe
 to further specify the query conditions.
 
 It is possible that you may want to call the same set of query methods in different places. If this is the case,
-you should consider defining the so-called *scopes*. A scope is essentially a method defined in a custom query class that
-calls a set of query methods to modify the query object. You can then use a scope like calling a normal query method.
+you should consider defining the so-called *scopes*. A scope is essentially a method defined in a custom query class that calls a set of query methods to modify the query object. You can then use a scope instead of calling a normal query method.
 
-Two steps are required to define a scope. First create a custom query class for your model and define the needed scope
+Two steps are required to define a scope. First, create a custom query class for your model and define the needed scope
 methods in this class. For example, create a `CommentQuery` class for the `Comment` model and define the `active()`
 scope method like the following:
 
@@ -949,7 +947,7 @@ class Post extends \yii\db\ActiveRecord
 }
 ```
 
-Or use the scopes on-the-fly when performing relational query:
+Or use the scopes on-the-fly when performing a relational query:
 
 ```php
 $posts = Post::find()->with([
@@ -980,8 +978,8 @@ Transactional operations
 ---------------------
 
 There are two ways of dealing with transactions while working with Active Record. First way is doing everything manually
-as described in "transactions" section of "[Database basics](db-dao.md)". Another way is to do it by implementing
-`transactions` method where you can specify which operations are to be wrapped into transaction per model scenario:
+as described in the "transactions" section of "[Database basics](db-dao.md)". Another way is to implement the
+`transactions` method where you can specify which operations are to be wrapped into transactions on a per model scenario:
 
 ```php
 class Post extends \yii\db\ActiveRecord
@@ -998,8 +996,8 @@ class Post extends \yii\db\ActiveRecord
 }
 ```
 
-In the above `admin` and `api` are model scenarios and constants starting with `OP_` are operations that should
-be wrapped in transaction for these scenarios. Supported operations are `OP_INSERT`, `OP_UPDATE` and `OP_DELETE`.
+In the above `admin` and `api` are model scenarios and the constants starting with `OP_` are operations that should
+be wrapped in transactions for these scenarios. Supported operations are `OP_INSERT`, `OP_UPDATE` and `OP_DELETE`.
 `OP_ALL` stands for all three.
 
 Such automatic transactions are especially useful if you're doing additional database changes in `beforeSave`,
@@ -1009,7 +1007,7 @@ Optimistic Locks
 --------------
 
 Optimistic locking allows multiple users to access the same record for edits and avoids
-potential conflicts. In case when a user attempts to save the record upon some staled data
+potential conflicts. For example, when a user attempts to save the record upon some staled data
 (because another user has modified the data), a [[\yii\db\StaleObjectException]] exception will be thrown,
 and the update or deletion is skipped.
 
@@ -1018,7 +1016,7 @@ Optimistic locking is only supported by `update()` and `delete()` methods and is
 To use Optimistic locking:
 
 1. Create a column to store the version number of each row. The column type should be `BIGINT DEFAULT 0`.
-   Override `optimisticLock()` method to return the name of this column.
+   Override the `optimisticLock()` method to return the name of this column.
 2. In the Web form that collects the user input, add a hidden field that stores
    the lock version of the recording being updated.
 3. In the controller action that does the data updating, try to catch the [[\yii\db\StaleObjectException]]
@@ -1028,9 +1026,7 @@ To use Optimistic locking:
 Dirty Attributes
 --------------
 
-An attribute is considered dirty if its value was modified since model was loaded from database or since most recent
-data save. When saving record data by calling `save()`, `update()`, `insert()` etc. only dirty attributes are saved
-into database. If there are no dirty attributes there's nothing to be saved so no query will be issued at all.
+An attribute is considered dirty if its value was modified after the model was loaded from database or since the most recent data save. When saving record data by calling `save()`, `update()`, `insert()` etc. only dirty attributes are saved into the database. If there are no dirty attributes then there is nothing to be saved so no query will be issued at all.
 
 See also
 --------