发布于 2015-08-01 11:22:59 | 296 次阅读 | 评论: 0 | 来源: 网络整理
In the Pagination and Sorting sections, we have described how to allow end users to choose a particular page of data to display and sort them by some columns. Because the task of paginating and sorting data is very common, Yii provides a set of data provider classes to encapsulate it.
A data provider is a class implementing yiidataDataProviderInterface. It mainly supports retrieving paginated and sorted data. It is usually used to work with data widgets so that end users can interactively paginate and sort data.
The following data provider classes are included in the Yii releases:
The usage of all these data providers share the following common pattern:
// create the data provider by configuring its pagination and sort properties
$provider = new XyzDataProvider([
'pagination' => [...],
'sort' => [...],
]);
// retrieves paginated and sorted data
$models = $provider->getModels();
// get the number of data items in the current page
$count = $provider->getCount();
// get the total number of data items across all pages
$totalCount = $provider->getTotalCount();
You specify the pagination and sorting behaviors of a data provider by configuring its yiidataBaseDataProvider::pagination and yiidataBaseDataProvider::sort properties which correspond to the configurations for yiidataPagination and yiidataSort, respectively. You may also configure them to be false to disable pagination and/or sorting features.
Data widgets, such as yiigridGridView, have a property named dataProvider which can take a data provider instance and display the data it provides. For example,
echo yiigridGridView::widget([
'dataProvider' => $dataProvider,
]);
These data providers mainly vary in the way how the data source is specified. In the following subsections, we will explain the detailed usage of each of these data providers.
To use yiidataActiveDataProvider, you should configure its yiidataActiveDataProvider::query property. It can take either a yiidbQuery or yiidbActiveQuery object. If the former, the data returned will be arrays; if the latter, the data returned can be either arrays or Active Record instances. For example,
use yiidataActiveDataProvider;
$query = Post::find()->where(['status' => 1]);
$provider = new ActiveDataProvider([
'query' => $query,
'pagination' => [
'pageSize' => 10,
],
'sort' => [
'defaultOrder' => [
'created_at' => SORT_DESC,
'title' => SORT_ASC,
]
],
]);
// returns an array of Post objects
$posts = $provider->getModels();
If $query in the above example is created using the following code, then the data provider will return raw arrays.
use yiidbQuery;
$query = (new Query())->from('post')->where(['status' => 1]);
Note: If a query already specifies the
orderByclause, the new ordering instructions given by end users (through thesortconfiguration) will be appended to the existingorderByclause. Any existinglimitandoffsetclauses will be overwritten by the pagination request from end users (through thepaginationconfiguration).
By default, yiidataActiveDataProvider uses the db application component as the database connection. You may use a different database connection by configuring the yiidataActiveDataProvider::db property.
yiidataSqlDataProvider works with a raw SQL statement which is used to fetch the needed data. Based on the specifications of yiidataSqlDataProvider::sort and yiidataSqlDataProvider::pagination, the provider will adjust the ORDER BY and LIMIT clauses of the SQL statement accordingly to fetch only the requested page of data in the desired order.
To use yiidataSqlDataProvider, you should specify the yiidataSqlDataProvider::sql property as well as the yiidataSqlDataProvider::totalCount property. For example,
use yiidataSqlDataProvider;
$count = Yii::$app->db->createCommand('
SELECT COUNT(*) FROM post WHERE status=:status
', [':status' => 1])->queryScalar();
$provider = new SqlDataProvider([
'sql' => 'SELECT * FROM post WHERE status=:status',
'params' => [':status' => 1],
'totalCount' => $count,
'pagination' => [
'pageSize' => 10,
],
'sort' => [
'attributes' => [
'title',
'view_count',
'created_at',
],
],
]);
// returns an array of data rows
$models = $provider->getModels();
Info: The yiidataSqlDataProvider::totalCount property is required only if you need to paginate the data. This is because the SQL statement specified via yiidataSqlDataProvider::sql will be modified by the provider to return only the currently requested page of data. The provider still needs to know the total number of data items in order to correctly calculate the number of pages available.
yiidataArrayDataProvider 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 yiidataArrayDataProvider, you should specify the yiidataArrayDataProvider::allModels property as the big array. Elements in the big array can be either associative arrays (e.g. query results of DAO) or objects (e.g. Active Record instances). For example,
use yiidataArrayDataProvider;
$data = [
['id' => 1, 'name' => 'name 1', ...],
['id' => 2, 'name' => 'name 2', ...],
...
['id' => 100, 'name' => 'name 100', ...],
];
$provider = new ArrayDataProvider([
'allModels' => $data,
'pagination' => [
'pageSize' => 10,
],
'sort' => [
'attributes' => ['id', 'name'],
],
]);
// get the rows in the currently requested page
$rows = $provider->getModels();
Note: Compared to Active Data Provider and SQL Data Provider, array data provider is less efficient because it requires loading all data into the memory.
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 yiidataDataProviderInterface::getModels(). For example,
use yiidataActiveDataProvider;
$query = Post::find()->where(['status' => 1]);
$provider = new ActiveDataProvider([
'query' => Post::find(),
]);
// returns an array of Post objects
$posts = $provider->getModels();
// returns the primary key values corresponding to $posts
$ids = $provider->getKeys();
In the above example, because you provide to yiidataActiveDataProvider an yiidbActiveQuery object, 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 yiidataActiveDataProvider::key with a column name or a callable calculating key values. For example,
// 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);
}
]);
To create your own custom data provider classes, you should implement yiidataDataProviderInterface. An easier way is to extend from yiidataBaseDataProvider which allows you to focus on the core data provider logic. In particular, you mainly need to implement the following methods:
Below is an example of a data provider that reads CSV data efficiently:
<?php
use yiidataBaseDataProvider;
class CsvDataProvider extends BaseDataProvider
{
/**
* @var string name of the CSV file to read
*/
public $filename;
/**
* @var string|callable name of the key column or a callable returning it
*/
public $key;
/**
* @var SplFileObject
*/
protected $fileObject; // SplFileObject is very convenient for seeking to particular line in a file
/**
* @inheritdoc
*/
public function init()
{
parent::init();
// open file
$this->fileObject = new SplFileObject($this->filename);
}
/**
* @inheritdoc
*/
protected function prepareModels()
{
$models = [];
$pagination = $this->getPagination();
if ($pagination === false) {
// in case there's no pagination, read all lines
while (!$this->fileObject->eof()) {
$models[] = $this->fileObject->fgetcsv();
$this->fileObject->next();
}
} else {
// in case there's pagination, read only a single page
$pagination->totalCount = $this->getTotalCount();
$this->fileObject->seek($pagination->getOffset());
$limit = $pagination->getLimit();
for ($count = 0; $count < $limit; ++$count) {
$models[] = $this->fileObject->fgetcsv();
$this->fileObject->next();
}
}
return $models;
}
/**
* @inheritdoc
*/
protected function prepareKeys($models)
{
if ($this->key !== null) {
$keys = [];
foreach ($models as $model) {
if (is_string($this->key)) {
$keys[] = $model[$this->key];
} else {
$keys[] = call_user_func($this->key, $model);
}
}
return $keys;
} else {
return array_keys($models);
}
}
/**
* @inheritdoc
*/
protected function prepareTotalCount()
{
$count = 0;
while (!$this->fileObject->eof()) {
$this->fileObject->next();
++$count;
}
return $count;
}
}