ArrayDataProvider.php 5.15 KB
Newer Older
Qiang Xue committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

namespace yii\data;

use yii\base\InvalidConfigException;
use yii\helpers\ArrayHelper;

/**
 * ArrayDataProvider implements a data provider based on a data array.
 *
 * The [[allItems]] property contains all data items that may be sorted and/or paginated.
 * ArrayDataProvider will provide the data after sorting and/or pagination.
 * You may configure the [[sort]] and [[pagination]] properties to
 * customize the sorting and pagination behaviors.
 *
 * Elements in the [[allItems]] array may be either objects (e.g. model objects)
 * or associative arrays (e.g. query results of DAO).
 * Make sure to set the [[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
 * because it needs to have [[allItems]] ready.
 *
 * ArrayDataProvider may be used in the following way:
 *
 * ~~~
 * $query = new Query;
 * $provider = new ArrayDataProvider(array(
 *     'allItems' => $query->from('tbl_post')->all(),
 *     'sort' => array(
 *         'attributes' => array(
 *              'id', 'username', 'email',
 *         ),
 *     ),
 *     'pagination' => array(
 *         'pageSize' => 10,
 *     ),
 * ));
 * // get the posts in the current page
 * $posts = $provider->getItems();
 * ~~~
 *
 * Note: if you want to use the sorting feature, you must configure the [[sort]] property
 * so that the provider knows which columns can be sorted.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
class ArrayDataProvider extends DataProvider
{
	/**
	 * @var string|callable the column that is used as the key of the data items.
	 * This can be either a column name, or a callable that returns the key value of a given data item.
	 * If this is not set, the index of the [[items]] array will be used.
	 * @see getKeys()
	 */
	public $key;
	/**
	 * @var array the data that is not paginated or sorted. When pagination is enabled,
	 * this property usually contains more elements than [[items]].
	 * The array elements must use zero-based integer keys.
	 */
	public $allItems;

Qiang Xue committed
70
	private $_totalCount;
Qiang Xue committed
71 72 73 74 75 76

	/**
	 * Returns the total number of data items.
	 * @return integer total number of possible data items.
	 * @throws InvalidConfigException
	 */
Qiang Xue committed
77
	public function getTotalCount()
Qiang Xue committed
78 79
	{
		if ($this->getPagination() === false) {
Qiang Xue committed
80 81
			return $this->getCount();
		} elseif ($this->_totalCount === null) {
Qiang Xue committed
82
			if ($this->allItems !== null) {
Qiang Xue committed
83
				$this->_totalCount = count($this->allItems);
Qiang Xue committed
84
			} else {
Qiang Xue committed
85
				throw new InvalidConfigException('Unable to determine total item count: either "allItems" or "totalCount" must be set.');
Qiang Xue committed
86 87
			}
		}
Qiang Xue committed
88
		return $this->_totalCount;
Qiang Xue committed
89 90 91 92 93 94
	}

	/**
	 * Sets the total number of data items.
	 * @param integer $value the total number of data items.
	 */
Qiang Xue committed
95
	public function setTotalCount($value)
Qiang Xue committed
96
	{
Qiang Xue committed
97
		$this->_totalCount = $value;
Qiang Xue committed
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
	}

	private $_items;

	/**
	 * Returns the data items in the current page.
	 * @return array the list of data items in the current page.
	 * @throws InvalidConfigException
	 */
	public function getItems()
	{
		if ($this->_items === null) {
			if (($items = $this->allItems) === null) {
				throw new InvalidConfigException('Either "items" or "allItems" must be set.');
			}

			if (($sort = $this->getSort()) !== false) {
				$items = $this->sortItems($items, $sort);
			}

			if (($pagination = $this->getPagination()) !== false) {
Qiang Xue committed
119
				$pagination->totalCount = $this->getTotalCount();
Qiang Xue committed
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
				$items = array_slice($items, $pagination->getOffset(), $pagination->getLimit());
			}

			$this->_items = $items;
		}
		return $this->_items;
	}

	/**
	 * Sets the data items in the current page.
	 * @param array $items the items in the current page
	 */
	public function setItems($items)
	{
		$this->_items = $items;
	}

	private $_keys;

	/**
	 * Returns the key values associated with the data items.
	 * @return array the list of key values corresponding to [[items]]. Each data item in [[items]]
	 * is uniquely identified by the corresponding key value in this array.
	 */
	public function getKeys()
	{
		if ($this->_keys === null) {
			$this->_keys = array();
			$items = $this->getItems();
			if ($this->key !== null) {
				foreach ($items as $item) {
					if (is_string($this->key)) {
						$this->_keys[] = $item[$this->key];
					} else {
						$this->_keys[] = call_user_func($this->key, $item);
					}
				}
			} else {
				$this->_keys = array_keys($items);
			}
		}
		return $this->_keys;
	}

	/**
	 * Sets the key values associated with the data items.
	 * @param array $keys the list of key values corresponding to [[items]].
	 */
	public function setKeys($keys)
	{
		$this->_keys = $keys;
	}

	/**
	 * Sorts the data items according to the given sort definition
	 * @param array $items the items to be sorted
	 * @param Sort $sort the sort definition
	 * @return array the sorted data items
	 */
	protected function sortItems($items, $sort)
	{
		$orders = $sort->getOrders();
		if (!empty($orders)) {
			ArrayHelper::multisort($items, array_keys($orders), array_values($orders));
		}
		return $items;
	}
}