QueryInterface.php 12KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255
  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. * The QueryInterface defines the minimum set of methods to be implemented by a database query.
  10. *
  11. * The default implementation of this interface is provided by [[QueryTrait]].
  12. *
  13. * It has support for getting [[one]] instance or [[all]].
  14. * Allows pagination via [[limit]] and [[offset]].
  15. * Sorting is supported via [[orderBy]] and items can be limited to match some conditions using [[where]].
  16. *
  17. * @author Qiang Xue <qiang.xue@gmail.com>
  18. * @author Carsten Brandt <mail@cebe.cc>
  19. * @since 2.0
  20. */
  21. interface QueryInterface
  22. {
  23. /**
  24. * Executes the query and returns all results as an array.
  25. * @param Connection $db the database connection used to execute the query.
  26. * If this parameter is not given, the `db` application component will be used.
  27. * @return array the query results. If the query results in nothing, an empty array will be returned.
  28. */
  29. public function all($db = null);
  30. /**
  31. * Executes the query and returns a single row of result.
  32. * @param Connection $db the database connection used to execute the query.
  33. * If this parameter is not given, the `db` application component will be used.
  34. * @return array|boolean the first row (in terms of an array) of the query result. False is returned if the query
  35. * results in nothing.
  36. */
  37. public function one($db = null);
  38. /**
  39. * Returns the number of records.
  40. * @param string $q the COUNT expression. Defaults to '*'.
  41. * @param Connection $db the database connection used to execute the query.
  42. * If this parameter is not given, the `db` application component will be used.
  43. * @return integer number of records.
  44. */
  45. public function count($q = '*', $db = null);
  46. /**
  47. * Returns a value indicating whether the query result contains any row of data.
  48. * @param Connection $db the database connection used to execute the query.
  49. * If this parameter is not given, the `db` application component will be used.
  50. * @return boolean whether the query result contains any row of data.
  51. */
  52. public function exists($db = null);
  53. /**
  54. * Sets the [[indexBy]] property.
  55. * @param string|callable $column the name of the column by which the query results should be indexed by.
  56. * This can also be a callable (e.g. anonymous function) that returns the index value based on the given
  57. * row data. The signature of the callable should be:
  58. *
  59. * ```php
  60. * function ($row)
  61. * {
  62. * // return the index value corresponding to $row
  63. * }
  64. * ```
  65. *
  66. * @return $this the query object itself
  67. */
  68. public function indexBy($column);
  69. /**
  70. * Sets the WHERE part of the query.
  71. *
  72. * The `$condition` specified as an array can be in one of the following two formats:
  73. *
  74. * - hash format: `['column1' => value1, 'column2' => value2, ...]`
  75. * - operator format: `[operator, operand1, operand2, ...]`
  76. *
  77. * A condition in hash format represents the following SQL expression in general:
  78. * `column1=value1 AND column2=value2 AND ...`. In case when a value is an array,
  79. * an `IN` expression will be generated. And if a value is `null`, `IS NULL` will be used
  80. * in the generated expression. Below are some examples:
  81. *
  82. * - `['type' => 1, 'status' => 2]` generates `(type = 1) AND (status = 2)`.
  83. * - `['id' => [1, 2, 3], 'status' => 2]` generates `(id IN (1, 2, 3)) AND (status = 2)`.
  84. * - `['status' => null]` generates `status IS NULL`.
  85. *
  86. * A condition in operator format generates the SQL expression according to the specified operator, which
  87. * can be one of the following:
  88. *
  89. * - **and**: the operands should be concatenated together using `AND`. For example,
  90. * `['and', 'id=1', 'id=2']` will generate `id=1 AND id=2`. If an operand is an array,
  91. * it will be converted into a string using the rules described here. For example,
  92. * `['and', 'type=1', ['or', 'id=1', 'id=2']]` will generate `type=1 AND (id=1 OR id=2)`.
  93. * The method will *not* do any quoting or escaping.
  94. *
  95. * - **or**: similar to the `and` operator except that the operands are concatenated using `OR`. For example,
  96. * `['or', ['type' => [7, 8, 9]], ['id' => [1, 2, 3]]]` will generate `(type IN (7, 8, 9) OR (id IN (1, 2, 3)))`.
  97. *
  98. * - **not**: this will take only one operand and build the negation of it by prefixing the query string with `NOT`.
  99. * For example `['not', ['attribute' => null]]` will result in the condition `NOT (attribute IS NULL)`.
  100. *
  101. * - **between**: operand 1 should be the column name, and operand 2 and 3 should be the
  102. * starting and ending values of the range that the column is in.
  103. * For example, `['between', 'id', 1, 10]` will generate `id BETWEEN 1 AND 10`.
  104. *
  105. * - **not between**: similar to `between` except the `BETWEEN` is replaced with `NOT BETWEEN`
  106. * in the generated condition.
  107. *
  108. * - **in**: operand 1 should be a column or DB expression, and operand 2 be an array representing
  109. * the range of the values that the column or DB expression should be in. For example,
  110. * `['in', 'id', [1, 2, 3]]` will generate `id IN (1, 2, 3)`.
  111. * The method will properly quote the column name and escape values in the range.
  112. *
  113. * To create a composite `IN` condition you can use and array for the column name and value, where the values are indexed by the column name:
  114. * `['in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']] ]`.
  115. *
  116. * You may also specify a sub-query that is used to get the values for the `IN`-condition:
  117. * `['in', 'user_id', (new Query())->select('id')->from('users')->where(['active' => 1])]`
  118. *
  119. * - **not in**: similar to the `in` operator except that `IN` is replaced with `NOT IN` in the generated condition.
  120. *
  121. * - **like**: operand 1 should be a column or DB expression, and operand 2 be a string or an array representing
  122. * the values that the column or DB expression should be like.
  123. * For example, `['like', 'name', 'tester']` will generate `name LIKE '%tester%'`.
  124. * When the value range is given as an array, multiple `LIKE` predicates will be generated and concatenated
  125. * using `AND`. For example, `['like', 'name', ['test', 'sample']]` will generate
  126. * `name LIKE '%test%' AND name LIKE '%sample%'`.
  127. * The method will properly quote the column name and escape special characters in the values.
  128. * Sometimes, you may want to add the percentage characters to the matching value by yourself, you may supply
  129. * a third operand `false` to do so. For example, `['like', 'name', '%tester', false]` will generate `name LIKE '%tester'`.
  130. *
  131. * - **or like**: similar to the `like` operator except that `OR` is used to concatenate the `LIKE`
  132. * predicates when operand 2 is an array.
  133. *
  134. * - **not like**: similar to the `like` operator except that `LIKE` is replaced with `NOT LIKE`
  135. * in the generated condition.
  136. *
  137. * - **or not like**: similar to the `not like` operator except that `OR` is used to concatenate
  138. * the `NOT LIKE` predicates.
  139. *
  140. * - **exists**: operand 1 is a query object that used to build an `EXISTS` condition. For example
  141. * `['exists', (new Query())->select('id')->from('users')->where(['active' => 1])]` will result in the following SQL expression:
  142. * `EXISTS (SELECT "id" FROM "users" WHERE "active"=1)`.
  143. *
  144. * - **not exists**: similar to the `exists` operator except that `EXISTS` is replaced with `NOT EXISTS` in the generated condition.
  145. *
  146. * - Additionally you can specify arbitrary operators as follows: A condition of `['>=', 'id', 10]` will result in the
  147. * following SQL expression: `id >= 10`.
  148. *
  149. * @param string|array $condition the conditions that should be put in the WHERE part.
  150. * @return $this the query object itself
  151. * @see andWhere()
  152. * @see orWhere()
  153. */
  154. public function where($condition);
  155. /**
  156. * Adds an additional WHERE condition to the existing one.
  157. * The new condition and the existing one will be joined using the 'AND' operator.
  158. * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
  159. * on how to specify this parameter.
  160. * @return $this the query object itself
  161. * @see where()
  162. * @see orWhere()
  163. */
  164. public function andWhere($condition);
  165. /**
  166. * Adds an additional WHERE condition to the existing one.
  167. * The new condition and the existing one will be joined using the 'OR' operator.
  168. * @param string|array $condition the new WHERE condition. Please refer to [[where()]]
  169. * on how to specify this parameter.
  170. * @return $this the query object itself
  171. * @see where()
  172. * @see andWhere()
  173. */
  174. public function orWhere($condition);
  175. /**
  176. * Sets the WHERE part of the query ignoring empty parameters.
  177. *
  178. * @param array $condition the conditions that should be put in the WHERE part. Please refer to [[where()]]
  179. * on how to specify this parameter.
  180. * @return $this the query object itself
  181. * @see andFilterWhere()
  182. * @see orFilterWhere()
  183. */
  184. public function filterWhere(array $condition);
  185. /**
  186. * Adds an additional WHERE condition to the existing one ignoring empty parameters.
  187. * The new condition and the existing one will be joined using the 'AND' operator.
  188. * @param array $condition the new WHERE condition. Please refer to [[where()]]
  189. * on how to specify this parameter.
  190. * @return $this the query object itself
  191. * @see filterWhere()
  192. * @see orFilterWhere()
  193. */
  194. public function andFilterWhere(array $condition);
  195. /**
  196. * Adds an additional WHERE condition to the existing one ignoring empty parameters.
  197. * The new condition and the existing one will be joined using the 'OR' operator.
  198. * @param array $condition the new WHERE condition. Please refer to [[where()]]
  199. * on how to specify this parameter.
  200. * @return $this the query object itself
  201. * @see filterWhere()
  202. * @see andFilterWhere()
  203. */
  204. public function orFilterWhere(array $condition);
  205. /**
  206. * Sets the ORDER BY part of the query.
  207. * @param string|array $columns the columns (and the directions) to be ordered by.
  208. * Columns can be specified in either a string (e.g. "id ASC, name DESC") or an array
  209. * (e.g. `['id' => SORT_ASC, 'name' => SORT_DESC]`).
  210. * The method will automatically quote the column names unless a column contains some parenthesis
  211. * (which means the column contains a DB expression).
  212. * @return $this the query object itself
  213. * @see addOrderBy()
  214. */
  215. public function orderBy($columns);
  216. /**
  217. * Adds additional ORDER BY columns to the query.
  218. * @param string|array $columns the columns (and the directions) to be ordered by.
  219. * Columns can be specified in either a string (e.g. "id ASC, name DESC") or an array
  220. * (e.g. `['id' => SORT_ASC, 'name' => SORT_DESC]`).
  221. * The method will automatically quote the column names unless a column contains some parenthesis
  222. * (which means the column contains a DB expression).
  223. * @return $this the query object itself
  224. * @see orderBy()
  225. */
  226. public function addOrderBy($columns);
  227. /**
  228. * Sets the LIMIT part of the query.
  229. * @param integer $limit the limit. Use null or negative value to disable limit.
  230. * @return $this the query object itself
  231. */
  232. public function limit($limit);
  233. /**
  234. * Sets the OFFSET part of the query.
  235. * @param integer $offset the offset. Use null or negative value to disable offset.
  236. * @return $this the query object itself
  237. */
  238. public function offset($offset);
  239. }