Merge branch 'master' of git://github.com/yiisoft/yii2 into doc_session-and-cooke_ru

docs/guide/output-data-providers.md

@@ -36,8 +36,10 @@ $count = $provider->getCount();
 $totalCount = $provider->getTotalCount();
 ```
 
-The `pagination` and `sort` properties of data providers correspond to the configurations for
+You specify the pagination and sorting behaviors of a data provider by configuring its 
-[[yii\data\Pagination]] and [[yii\data\Sort]], respectively.
+[[yii\data\BaseDataProvider::pagination|pagination]] and [[yii\data\BaseDataProvider::sort|sort]] properties
+which correspond to the configurations for [[yii\data\Pagination]] and [[yii\data\Sort]], respectively.
+You may also configure them to be false to disable pagination and/or sorting features.
 
 [Data widgets](output-data-widgets.md), such as [[yii\grid\GridView]], have a property named `dataProvider` which
 can take a data provider instance and display the data it provides. For example,
@@ -67,7 +69,7 @@ $query = Post::find()->where(['status' => 1]);
 $provider = new ActiveDataProvider([
     'query' => Post::find(),
     'pagination' => [
-        'pageSize' => 20,
+        'pageSize' => 10,
     ],
     'sort' => [
         'defaultOrder' => [
@@ -99,104 +101,152 @@ use a different database connection by configuring the [[yii\data\ActiveDataProv
 
 ## SQL Data Provider <span id="sql-data-provider"></span>
 
-Like other data providers, SqlDataProvider also supports sorting and pagination. It does so by modifying the given
+[[yii\data\SqlDataProvider]] works with a raw SQL statement which is used to fetch the needed
-[[yii\data\SqlDataProvider::$sql]] statement with "ORDER BY" and "LIMIT" clauses. You may configure the
+data. Based on the specifications of [[yii\data\SqlDataProvider::sort|sort]] and 
-[[yii\data\SqlDataProvider::$sort]] and [[yii\data\SqlDataProvider::$pagination]] properties to customize sorting
+[[yii\data\SqlDataProvider::pagination|pagination]], the provider will adjust the `ORDER BY` and `LIMIT`
-and pagination behaviors.
+clauses of the SQL statement accordingly to fetch only the requested page of data in the desired order.
 
-`SqlDataProvider` may be used in the following way:
+To use [[yii\data\SqlDataProvider]], you should specify the [[yii\data\SqlDataProvider::sql|sql]] property as well
+as the [[yii\data\SqlDataProvider::totalCount|totalCount]] property. For example,
 
 ```php
+use yii\data\SqlDataProvider;
+
 $count = Yii::$app->db->createCommand('
-    SELECT COUNT(*) FROM user WHERE status=:status
+    SELECT COUNT(*) FROM post WHERE status=:status
 ', [':status' => 1])->queryScalar();
 
-$dataProvider = new SqlDataProvider([
+$provider = new SqlDataProvider([
-    'sql' => 'SELECT * FROM user WHERE status=:status',
+    'sql' => 'SELECT * FROM post WHERE status=:status',
     'params' => [':status' => 1],
     'totalCount' => $count,
+    'pagination' => [
+        'pageSize' => 10,
+    ],
     'sort' => [
         'attributes' => [
-            'age',
+            'title',
-            'name' => [
+            'view_count',
-                'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
+            'created_at',
-                'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
-                'default' => SORT_DESC,
-                'label' => 'Name',
-            ],
         ],
     ],
-    'pagination' => [
-        'pageSize' => 20,
-    ],
 ]);
 
-// get the user records in the current page
+// returns an array of data rows
-$models = $dataProvider->getModels();
+$models = $provider->getModels();
 ```
 
-> Note: if you want to use the pagination feature, you must configure the [[yii\data\SqlDataProvider::$totalCount]]
+> Info: The [[yii\data\SqlDataProvider::totalCount|totalCount]] property is required only if you need to
-property to be the total number of rows (without pagination). And if you want to use the sorting feature,
+  paginate the data. This is because the SQL statement specified via [[yii\data\SqlDataProvider::sql|sql]]
-you must configure the [[yii\data\SqlDataProvider::$sort]] property so that the provider knows which columns can
+  will be modified by the provider to return only the currently requested page of data. The provider still
-be sorted.
+  needs to know the total number of data items in order to correctly calculate the number of pages available.
 
 
 ## Array Data Provider <span id="array-data-provider"></span>
 
-ArrayDataProvider implements a data provider based on a data array.
+[[yii\data\ArrayDataProvider]] is best used when working with a big array. The provider allows you to return
-
+a page of the array data sorted by one or multiple columns. To use [[yii\data\ArrayDataProvider]], you should
-The [[yii\data\ArrayDataProvider::$allModels]] property contains all data models that may be sorted and/or paginated.
+specify the [[yii\data\ArrayDataProvider::allModels|allModels]] property as the big array.
-ArrayDataProvider will provide the data after sorting and/or pagination.
+Elements in the big array can be either associative arrays
-You may configure the [[yii\data\ArrayDataProvider::$sort]] and [[yii\data\ArrayDataProvider::$pagination]] properties to
+(e.g. query results of [DAO](db-dao.md)) or objects (e.g. [Active Record](db-active-record.md) instances).
-customize the sorting and pagination behaviors.
+For example,
-
-Elements in the [[yii\data\ArrayDataProvider::$allModels]] array may be either objects (e.g. model objects)
-or associative arrays (e.g. query results of DAO).
-Make sure to set the [[yii\data\ArrayDataProvider::$key]] property to the name of the field that uniquely
-identifies a data record or false if you do not have such a field.
 
-Compared to `ActiveDataProvider`, `ArrayDataProvider` could be less efficient
+```php
-because it needs to have [[yii\data\ArrayDataProvider::$allModels]] ready.
+use yii\data\ArrayDataProvider;
 
-ArrayDataProvider may be used in the following way:
+$data = [
+    ['id' => 1, 'name' => 'name 1', ...],
+    ['id' => 2, 'name' => 'name 2', ...],
+    ...
+    ['id' => 100, 'name' => 'name 100', ...],
+];
 
-```php
-$query = new Query();
 $provider = new ArrayDataProvider([
-    'allModels' => $query->from('post')->all(),
+    'allModels' => $data,
-    'sort' => [
-        'attributes' => ['id', 'username', 'email'],
-    ],
     'pagination' => [
         'pageSize' => 10,
     ],
+    'sort' => [
+        'attributes' => ['id', 'name'],
+    ],
+]);
+
+// get the rows in the currently requested page
+$rows = $provider->getModels();
+``` 
+
+> Note: Compared to [Active Data Provider](#active-data-provider) and [SQL Data Provider](#sql-data-provider),
+  array data provider is less efficient because it requires loading *all* data into the memory.
+
+
+## Working with Data Keys <span id="working-with-keys"></span>
+
+When using the data items returned by a data provider, you often need to identify each data item with a unique key.
+For example, if the data items represent customer information, you may want to use the customer ID as the key
+for each customer data. Data providers can return a list of such keys corresponding with the data items returned 
+by [[yii\data\DataProviderInterface::getModels()]]. For example,
+
+```php
+use yii\data\ActiveDataProvider;
+
+$query = Post::find()->where(['status' => 1]);
+
+$provider = new ActiveDataProvider([
+    'query' => Post::find(),
 ]);
-// get the posts in the current page
+
+// returns an array of Post objects
 $posts = $provider->getModels();
+
+// returns the primary key values corresponding to $posts
+$ids = $provider->getKeys();
 ```
 
-> Note: if you want to use the sorting feature, you must configure the [[sort]] property
+In the above example, because you provide to [[yii\data\ActiveDataProvider]] an [[yii\db\ActiveQuery]] object,
-so that the provider knows which columns can be sorted.
+it is intelligent enough to return primary key values as the keys. You may also explicitly specify how the key
+values should be calculated by configuring [[yii\data\ActiveDataProvider::key]] with a column name or
+a callable calculating key values. For example,
+
+```php
+// use "slug" column as key values
+$provider = new ActiveDataProvider([
+    'query' => Post::find(),
+    'key' => 'slug',
+]);
+
+// use the result of md5(id) as key values
+$provider = new ActiveDataProvider([
+    'query' => Post::find(),
+    'key' => function ($model) {
+        return md5($model->id);
+    }
+]);
+```
 
 
-Implementing your own custom data provider
+## Creating Custom Data Provider <span id="custom-data-provider"></span>
-------------------------------------------
 
-Yii allows you to introduce your own custom data providers. In order to do it you need to implement the following
+To create your own custom data provider classes, you should implement [[yii\data\DataProviderInterface]].
-`protected` methods:
+An easier way is to extend from [[yii\data\BaseDataProvider]] which allows you to focus on the core data provider
+logic. In particular, you mainly need to implement the following methods:
                                                    
-- `prepareModels` that prepares the data models that will be made available in the current page and returns them as an array.
+- [[yii\data\BaseDataProvider::prepareModels()|prepareModels()]]: prepares the data models that will be made 
-- `prepareKeys` that accepts an array of currently available data models and returns keys associated with them.
+  available in the current page and returns them as an array.
-- `prepareTotalCount` that returns a value indicating the total number of data models in the data provider.
+- [[yii\data\BaseDataProvider::prepareKeys()|prepareKeys()]]: accepts an array of currently available data models
+  and returns keys associated with them.
+- [[yii\data\BaseDataProvider::prepareTotalCount()|prepareTotalCount]]: returns a value indicating the total number 
+  of data models in the data provider.
 
-Below is an example of a data provider that reads CSV efficiently:
+Below is an example of a data provider that reads CSV data efficiently:
 
 ```php
 <?php
-class CsvDataProvider extends \yii\data\BaseDataProvider
+use yii\data\BaseDataProvider;
+
+class CsvDataProvider extends BaseDataProvider
 {
     /**
-     * @var string name of the file to read
+     * @var string name of the CSV file to read
      */
     public $filename;
     
@@ -289,4 +339,3 @@ class CsvDataProvider extends \yii\data\BaseDataProvider
     }
 }
 ```
- 

docs/internals/translation-status.md

@@ -58,7 +58,7 @@ input-tabular-input.md              |
 output-formatting.md                |
 output-pagination.md                | Yes
 output-sorting.md                   | Yes
-output-data-providers.md            |
+output-data-providers.md            | Yes
 output-data-widgets.md              |
 output-theming.md                   |
 security-authentication.md          |