ActiveQueryTrait.php 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194
  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\db;
  8. /**
  9. * ActiveQueryTrait implements the common methods and properties for active record query classes.
  10. *
  11. * @author Qiang Xue <qiang.xue@gmail.com>
  12. * @author Carsten Brandt <mail@cebe.cc>
  13. * @since 2.0
  14. */
  15. trait ActiveQueryTrait
  16. {
  17. /**
  18. * @var string the name of the ActiveRecord class.
  19. */
  20. public $modelClass;
  21. /**
  22. * @var array a list of relations that this query should be performed with
  23. */
  24. public $with;
  25. /**
  26. * @var bool whether to return each record as an array. If false (default), an object
  27. * of [[modelClass]] will be created to represent each record.
  28. */
  29. public $asArray;
  30. /**
  31. * Sets the [[asArray]] property.
  32. * @param bool $value whether to return the query results in terms of arrays instead of Active Records.
  33. * @return $this the query object itself
  34. */
  35. public function asArray($value = true)
  36. {
  37. $this->asArray = $value;
  38. return $this;
  39. }
  40. /**
  41. * Specifies the relations with which this query should be performed.
  42. *
  43. * The parameters to this method can be either one or multiple strings, or a single array
  44. * of relation names and the optional callbacks to customize the relations.
  45. *
  46. * A relation name can refer to a relation defined in [[modelClass]]
  47. * or a sub-relation that stands for a relation of a related record.
  48. * For example, `orders.address` means the `address` relation defined
  49. * in the model class corresponding to the `orders` relation.
  50. *
  51. * The following are some usage examples:
  52. *
  53. * ```php
  54. * // find customers together with their orders and country
  55. * Customer::find()->with('orders', 'country')->all();
  56. * // find customers together with their orders and the orders' shipping address
  57. * Customer::find()->with('orders.address')->all();
  58. * // find customers together with their country and orders of status 1
  59. * Customer::find()->with([
  60. * 'orders' => function (\yii\db\ActiveQuery $query) {
  61. * $query->andWhere('status = 1');
  62. * },
  63. * 'country',
  64. * ])->all();
  65. * ```
  66. *
  67. * You can call `with()` multiple times. Each call will add relations to the existing ones.
  68. * For example, the following two statements are equivalent:
  69. *
  70. * ```php
  71. * Customer::find()->with('orders', 'country')->all();
  72. * Customer::find()->with('orders')->with('country')->all();
  73. * ```
  74. *
  75. * @return $this the query object itself
  76. */
  77. public function with()
  78. {
  79. $with = func_get_args();
  80. if (isset($with[0]) && is_array($with[0])) {
  81. // the parameter is given as an array
  82. $with = $with[0];
  83. }
  84. if (empty($this->with)) {
  85. $this->with = $with;
  86. } elseif (!empty($with)) {
  87. foreach ($with as $name => $value) {
  88. if (is_int($name)) {
  89. // repeating relation is fine as normalizeRelations() handle it well
  90. $this->with[] = $value;
  91. } else {
  92. $this->with[$name] = $value;
  93. }
  94. }
  95. }
  96. return $this;
  97. }
  98. /**
  99. * Converts found rows into model instances.
  100. * @param array $rows
  101. * @return array|ActiveRecord[]
  102. * @since 2.0.11
  103. */
  104. protected function createModels($rows)
  105. {
  106. if ($this->asArray) {
  107. return $rows;
  108. } else {
  109. $models = [];
  110. /* @var $class ActiveRecord */
  111. $class = $this->modelClass;
  112. foreach ($rows as $row) {
  113. $model = $class::instantiate($row);
  114. $modelClass = get_class($model);
  115. $modelClass::populateRecord($model, $row);
  116. $models[] = $model;
  117. }
  118. return $models;
  119. }
  120. }
  121. /**
  122. * Finds records corresponding to one or multiple relations and populates them into the primary models.
  123. * @param array $with a list of relations that this query should be performed with. Please
  124. * refer to [[with()]] for details about specifying this parameter.
  125. * @param array|ActiveRecord[] $models the primary models (can be either AR instances or arrays)
  126. */
  127. public function findWith($with, &$models)
  128. {
  129. $primaryModel = reset($models);
  130. if (!$primaryModel instanceof ActiveRecordInterface) {
  131. /* @var $modelClass ActiveRecordInterface */
  132. $modelClass = $this->modelClass;
  133. $primaryModel = $modelClass::instance();
  134. }
  135. $relations = $this->normalizeRelations($primaryModel, $with);
  136. /* @var $relation ActiveQuery */
  137. foreach ($relations as $name => $relation) {
  138. if ($relation->asArray === null) {
  139. // inherit asArray from primary query
  140. $relation->asArray($this->asArray);
  141. }
  142. $relation->populateRelation($name, $models);
  143. }
  144. }
  145. /**
  146. * @param ActiveRecord $model
  147. * @param array $with
  148. * @return ActiveQueryInterface[]
  149. */
  150. private function normalizeRelations($model, $with)
  151. {
  152. $relations = [];
  153. foreach ($with as $name => $callback) {
  154. if (is_int($name)) {
  155. $name = $callback;
  156. $callback = null;
  157. }
  158. if (($pos = strpos($name, '.')) !== false) {
  159. // with sub-relations
  160. $childName = substr($name, $pos + 1);
  161. $name = substr($name, 0, $pos);
  162. } else {
  163. $childName = null;
  164. }
  165. if (!isset($relations[$name])) {
  166. $relation = $model->getRelation($name);
  167. $relation->primaryModel = null;
  168. $relations[$name] = $relation;
  169. } else {
  170. $relation = $relations[$name];
  171. }
  172. if (isset($childName)) {
  173. $relation->with[$childName] = $callback;
  174. } elseif ($callback !== null) {
  175. call_user_func($callback, $relation);
  176. }
  177. }
  178. return $relations;
  179. }
  180. }