ConditionInterface.php 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
  1. <?php
  2. namespace Drupal\Core\Database\Query;
  3. use Drupal\Core\Database\Connection;
  4. /**
  5. * Interface for a conditional clause in a query.
  6. */
  7. interface ConditionInterface {
  8. /**
  9. * Helper function: builds the most common conditional clauses.
  10. *
  11. * This method takes 1 to 3 parameters.
  12. *
  13. * If called with 1 parameter, it should be a ConditionInterface that in
  14. * itself forms a valid where clause. Use e.g. to build clauses with nested
  15. * AND's and OR's.
  16. *
  17. * If called with 2 parameters, they are taken as $field and $value with
  18. * $operator having a value of =.
  19. *
  20. * Do not use this method to test for NULL values. Instead, use
  21. * QueryConditionInterface::isNull() or QueryConditionInterface::isNotNull().
  22. *
  23. * To improve readability, the operators EXISTS and NOT EXISTS have their own
  24. * utility method defined.
  25. *
  26. * Drupal considers LIKE case insensitive and the following is often used
  27. * to tell the database that case insensitive equivalence is desired:
  28. * @code
  29. * db_select('users')
  30. * ->condition('name', db_like($name), 'LIKE')
  31. * @endcode
  32. * Use 'LIKE BINARY' instead of 'LIKE' for case sensitive queries.
  33. *
  34. * Note: When using MySQL, the exact behavior also depends on the used
  35. * collation. if the field is set to binary, then a LIKE condition will also
  36. * be case sensitive and when a case insensitive collation is used, the =
  37. * operator will also be case insensitive.
  38. *
  39. * @param string|\Drupal\Core\Database\Query\ConditionInterface $field
  40. * The name of the field to check. This can also be QueryConditionInterface
  41. * in itself. Use where(), if you would like to add a more complex condition
  42. * involving operators or functions, or an already compiled condition.
  43. * @param string|array|\Drupal\Core\Database\Query\SelectInterface|null $value
  44. * The value to test the field against. In most cases, and depending on the
  45. * operator, this will be a scalar or an array. As SQL accepts select
  46. * queries on any place where a scalar value or set is expected, $value may
  47. * also be a(n array of) SelectInterface(s). If $operator is a unary
  48. * operator, e.g. IS NULL, $value will be ignored and should be null. If
  49. * the operator requires a subquery, e.g. EXISTS, the $field will be ignored
  50. * and $value should be a SelectInterface object.
  51. * @param string|null $operator
  52. * The operator to use. Supported for all supported databases are at least:
  53. * - The comparison operators =, <>, <, <=, >, >=.
  54. * - The operators (NOT) BETWEEN, (NOT) IN, (NOT) EXISTS, (NOT) LIKE.
  55. * Other operators (e.g. LIKE, BINARY) may or may not work. Defaults to =.
  56. *
  57. * @return \Drupal\Core\Database\Query\ConditionInterface
  58. * The called object.
  59. *
  60. * @throws \Drupal\Core\Database\InvalidQueryException
  61. * If passed invalid arguments, such as an empty array as $value.
  62. *
  63. * @see \Drupal\Core\Database\Query\ConditionInterface::isNull()
  64. * @see \Drupal\Core\Database\Query\ConditionInterface::isNotNull()
  65. * @see \Drupal\Core\Database\Query\ConditionInterface::exists()
  66. * @see \Drupal\Core\Database\Query\ConditionInterface::notExist()
  67. * @see \Drupal\Core\Database\Query\ConditionInterface::where()
  68. */
  69. public function condition($field, $value = NULL, $operator = '=');
  70. /**
  71. * Adds an arbitrary WHERE clause to the query.
  72. *
  73. * @param string $snippet
  74. * A portion of a WHERE clause as a prepared statement. It must use named
  75. * placeholders, not ? placeholders. The caller is responsible for providing
  76. * unique placeholders that do not interfere with the placeholders generated
  77. * by this QueryConditionInterface object.
  78. * @param array $args
  79. * An associative array of arguments keyed by the named placeholders.
  80. *
  81. * @return \Drupal\Core\Database\Query\ConditionInterface
  82. * The called object.
  83. */
  84. public function where($snippet, $args = []);
  85. /**
  86. * Sets a condition that the specified field be NULL.
  87. *
  88. * @param string|\Drupal\Core\Database\Query\SelectInterface $field
  89. * The name of the field or a subquery to check.
  90. *
  91. * @return \Drupal\Core\Database\Query\ConditionInterface
  92. * The called object.
  93. */
  94. public function isNull($field);
  95. /**
  96. * Sets a condition that the specified field be NOT NULL.
  97. *
  98. * @param string|\Drupal\Core\Database\Query\SelectInterface $field
  99. * The name of the field or a subquery to check.
  100. *
  101. * @return \Drupal\Core\Database\Query\ConditionInterface
  102. * The called object.
  103. */
  104. public function isNotNull($field);
  105. /**
  106. * Sets a condition that the specified subquery returns values.
  107. *
  108. * @param \Drupal\Core\Database\Query\SelectInterface $select
  109. * The subquery that must contain results.
  110. *
  111. * @return \Drupal\Core\Database\Query\ConditionInterface
  112. * The called object.
  113. */
  114. public function exists(SelectInterface $select);
  115. /**
  116. * Sets a condition that the specified subquery returns no values.
  117. *
  118. * @param \Drupal\Core\Database\Query\SelectInterface $select
  119. * The subquery that must not contain results.
  120. *
  121. * @return \Drupal\Core\Database\Query\ConditionInterface
  122. * The called object.
  123. */
  124. public function notExists(SelectInterface $select);
  125. /**
  126. * Gets the, possibly nested, list of conditions in this conditional clause.
  127. *
  128. * This method returns by reference. That allows alter hooks to access the
  129. * data structure directly and manipulate it before it gets compiled.
  130. *
  131. * The data structure that is returned is an indexed array of entries, where
  132. * each entry looks like the following:
  133. * @code
  134. * array(
  135. * 'field' => $field,
  136. * 'value' => $value,
  137. * 'operator' => $operator,
  138. * );
  139. * @endcode
  140. *
  141. * In the special case that $operator is NULL, the $field is taken as a raw
  142. * SQL snippet (possibly containing a function) and $value is an associative
  143. * array of placeholders for the snippet.
  144. *
  145. * There will also be a single array entry of #conjunction, which is the
  146. * conjunction that will be applied to the array, such as AND.
  147. *
  148. * @return array
  149. * The, possibly nested, list of all conditions (by reference).
  150. */
  151. public function &conditions();
  152. /**
  153. * Gets a complete list of all values to insert into the prepared statement.
  154. *
  155. * @return
  156. * An associative array of placeholders and values.
  157. */
  158. public function arguments();
  159. /**
  160. * Compiles the saved conditions for later retrieval.
  161. *
  162. * This method does not return anything, but simply prepares data to be
  163. * retrieved via __toString() and arguments().
  164. *
  165. * @param $connection
  166. * The database connection for which to compile the conditionals.
  167. * @param $queryPlaceholder
  168. * The query this condition belongs to. If not given, the current query is
  169. * used.
  170. */
  171. public function compile(Connection $connection, PlaceholderInterface $queryPlaceholder);
  172. /**
  173. * Check whether a condition has been previously compiled.
  174. *
  175. * @return
  176. * TRUE if the condition has been previously compiled.
  177. */
  178. public function compiled();
  179. /**
  180. * Creates an object holding a group of conditions.
  181. *
  182. * See andConditionGroup() and orConditionGroup() for more.
  183. *
  184. * @param $conjunction
  185. * - AND (default): this is the equivalent of andConditionGroup().
  186. * - OR: this is the equivalent of orConditionGroup().
  187. *
  188. * @return \Drupal\Core\Database\Query\ConditionInterface
  189. * An object holding a group of conditions.
  190. */
  191. public function conditionGroupFactory($conjunction = 'AND');
  192. /**
  193. * Creates a new group of conditions ANDed together.
  194. *
  195. * @return \Drupal\Core\Database\Query\ConditionInterface
  196. */
  197. public function andConditionGroup();
  198. /**
  199. * Creates a new group of conditions ORed together.
  200. *
  201. * @return \Drupal\Core\Database\Query\ConditionInterface
  202. */
  203. public function orConditionGroup();
  204. }