257 line
8.5KB

  1. <?php
  2. /**
  3. * @link http://www.yiiframework.com/
  4. * @copyright Copyright (c) 2008 Yii Software LLC
  5. * @license http://www.yiiframework.com/license/
  6. */
  7. namespace yii\data;
  8. use Yii;
  9. use yii\base\Component;
  10. use yii\base\InvalidParamException;
  11. /**
  12. * BaseDataProvider provides a base class that implements the [[DataProviderInterface]].
  13. *
  14. * @property integer $count The number of data models in the current page. This property is read-only.
  15. * @property array $keys The list of key values corresponding to [[models]]. Each data model in [[models]] is
  16. * uniquely identified by the corresponding key value in this array.
  17. * @property array $models The list of data models in the current page.
  18. * @property Pagination|boolean $pagination The pagination object. If this is false, it means the pagination
  19. * is disabled. Note that the type of this property differs in getter and setter. See [[getPagination()]] and
  20. * [[setPagination()]] for details.
  21. * @property Sort|boolean $sort The sorting object. If this is false, it means the sorting is disabled. Note
  22. * that the type of this property differs in getter and setter. See [[getSort()]] and [[setSort()]] for details.
  23. * @property integer $totalCount Total number of possible data models.
  24. *
  25. * @author Qiang Xue <qiang.xue@gmail.com>
  26. * @since 2.0
  27. */
  28. abstract class BaseDataProvider extends Component implements DataProviderInterface
  29. {
  30. /**
  31. * @var string an ID that uniquely identifies the data provider among all data providers.
  32. * You should set this property if the same page contains two or more different data providers.
  33. * Otherwise, the [[pagination]] and [[sort]] may not work properly.
  34. */
  35. public $id;
  36. private $_sort;
  37. private $_pagination;
  38. private $_keys;
  39. private $_models;
  40. private $_totalCount;
  41. /**
  42. * Prepares the data models that will be made available in the current page.
  43. * @return array the available data models
  44. */
  45. abstract protected function prepareModels();
  46. /**
  47. * Prepares the keys associated with the currently available data models.
  48. * @param array $models the available data models
  49. * @return array the keys
  50. */
  51. abstract protected function prepareKeys($models);
  52. /**
  53. * Returns a value indicating the total number of data models in this data provider.
  54. * @return integer total number of data models in this data provider.
  55. */
  56. abstract protected function prepareTotalCount();
  57. /**
  58. * Prepares the data models and keys.
  59. *
  60. * This method will prepare the data models and keys that can be retrieved via
  61. * [[getModels()]] and [[getKeys()]].
  62. *
  63. * This method will be implicitly called by [[getModels()]] and [[getKeys()]] if it has not been called before.
  64. *
  65. * @param boolean $forcePrepare whether to force data preparation even if it has been done before.
  66. */
  67. public function prepare($forcePrepare = false)
  68. {
  69. if ($forcePrepare || $this->_models === null) {
  70. $this->_models = $this->prepareModels();
  71. }
  72. if ($forcePrepare || $this->_keys === null) {
  73. $this->_keys = $this->prepareKeys($this->_models);
  74. }
  75. }
  76. /**
  77. * Returns the data models in the current page.
  78. * @return array the list of data models in the current page.
  79. */
  80. public function getModels()
  81. {
  82. $this->prepare();
  83. return $this->_models;
  84. }
  85. /**
  86. * Sets the data models in the current page.
  87. * @param array $models the models in the current page
  88. */
  89. public function setModels($models)
  90. {
  91. $this->_models = $models;
  92. }
  93. /**
  94. * Returns the key values associated with the data models.
  95. * @return array the list of key values corresponding to [[models]]. Each data model in [[models]]
  96. * is uniquely identified by the corresponding key value in this array.
  97. */
  98. public function getKeys()
  99. {
  100. $this->prepare();
  101. return $this->_keys;
  102. }
  103. /**
  104. * Sets the key values associated with the data models.
  105. * @param array $keys the list of key values corresponding to [[models]].
  106. */
  107. public function setKeys($keys)
  108. {
  109. $this->_keys = $keys;
  110. }
  111. /**
  112. * Returns the number of data models in the current page.
  113. * @return integer the number of data models in the current page.
  114. */
  115. public function getCount()
  116. {
  117. return count($this->getModels());
  118. }
  119. /**
  120. * Returns the total number of data models.
  121. * When [[pagination]] is false, this returns the same value as [[count]].
  122. * Otherwise, it will call [[prepareTotalCount()]] to get the count.
  123. * @return integer total number of possible data models.
  124. */
  125. public function getTotalCount()
  126. {
  127. if ($this->getPagination() === false) {
  128. return $this->getCount();
  129. } elseif ($this->_totalCount === null) {
  130. $this->_totalCount = $this->prepareTotalCount();
  131. }
  132. return $this->_totalCount;
  133. }
  134. /**
  135. * Sets the total number of data models.
  136. * @param integer $value the total number of data models.
  137. */
  138. public function setTotalCount($value)
  139. {
  140. $this->_totalCount = $value;
  141. }
  142. /**
  143. * Returns the pagination object used by this data provider.
  144. * Note that you should call [[prepare()]] or [[getModels()]] first to get correct values
  145. * of [[Pagination::totalCount]] and [[Pagination::pageCount]].
  146. * @return Pagination|boolean the pagination object. If this is false, it means the pagination is disabled.
  147. */
  148. public function getPagination()
  149. {
  150. if ($this->_pagination === null) {
  151. $this->setPagination([]);
  152. }
  153. return $this->_pagination;
  154. }
  155. /**
  156. * Sets the pagination for this data provider.
  157. * @param array|Pagination|boolean $value the pagination to be used by this data provider.
  158. * This can be one of the following:
  159. *
  160. * - a configuration array for creating the pagination object. The "class" element defaults
  161. * to 'yii\data\Pagination'
  162. * - an instance of [[Pagination]] or its subclass
  163. * - false, if pagination needs to be disabled.
  164. *
  165. * @throws InvalidParamException
  166. */
  167. public function setPagination($value)
  168. {
  169. if (is_array($value)) {
  170. $config = ['class' => Pagination::className()];
  171. if ($this->id !== null) {
  172. $config['pageParam'] = $this->id . '-page';
  173. $config['pageSizeParam'] = $this->id . '-per-page';
  174. }
  175. $this->_pagination = Yii::createObject(array_merge($config, $value));
  176. } elseif ($value instanceof Pagination || $value === false) {
  177. $this->_pagination = $value;
  178. } else {
  179. throw new InvalidParamException('Only Pagination instance, configuration array or false is allowed.');
  180. }
  181. }
  182. /**
  183. * Returns the sorting object used by this data provider.
  184. * @return Sort|boolean the sorting object. If this is false, it means the sorting is disabled.
  185. */
  186. public function getSort()
  187. {
  188. if ($this->_sort === null) {
  189. $this->setSort([]);
  190. }
  191. return $this->_sort;
  192. }
  193. /**
  194. * Sets the sort definition for this data provider.
  195. * @param array|Sort|boolean $value the sort definition to be used by this data provider.
  196. * This can be one of the following:
  197. *
  198. * - a configuration array for creating the sort definition object. The "class" element defaults
  199. * to 'yii\data\Sort'
  200. * - an instance of [[Sort]] or its subclass
  201. * - false, if sorting needs to be disabled.
  202. *
  203. * @throws InvalidParamException
  204. */
  205. public function setSort($value)
  206. {
  207. if (is_array($value)) {
  208. $config = ['class' => Sort::className()];
  209. if ($this->id !== null) {
  210. $config['sortParam'] = $this->id . '-sort';
  211. }
  212. $this->_sort = Yii::createObject(array_merge($config, $value));
  213. } elseif ($value instanceof Sort || $value === false) {
  214. $this->_sort = $value;
  215. } else {
  216. throw new InvalidParamException('Only Sort instance, configuration array or false is allowed.');
  217. }
  218. }
  219. /**
  220. * Refreshes the data provider.
  221. * After calling this method, if [[getModels()]], [[getKeys()]] or [[getTotalCount()]] is called again,
  222. * they will re-execute the query and return the latest data available.
  223. */
  224. public function refresh()
  225. {
  226. $this->_totalCount = null;
  227. $this->_models = null;
  228. $this->_keys = null;
  229. }
  230. }