3 namespace Drupal\Core\Database\Query;
5 use Drupal\Core\Database\Connection;
8 * Interface for a conditional clause in a query.
10 interface ConditionInterface {
13 * Helper function: builds the most common conditional clauses.
15 * This method takes 1 to 3 parameters.
17 * If called with 1 parameter, it should be a ConditionInterface that in
18 * itself forms a valid where clause. Use e.g. to build clauses with nested
21 * If called with 2 parameters, they are taken as $field and $value with
22 * $operator having a value of =.
24 * Do not use this method to test for NULL values. Instead, use
25 * QueryConditionInterface::isNull() or QueryConditionInterface::isNotNull().
27 * To improve readability, the operators EXISTS and NOT EXISTS have their own
28 * utility method defined.
30 * Drupal considers LIKE case insensitive and the following is often used
31 * to tell the database that case insensitive equivalence is desired:
34 * ->condition('name', db_like($name), 'LIKE')
36 * Use 'LIKE BINARY' instead of 'LIKE' for case sensitive queries.
38 * Note: When using MySQL, the exact behavior also depends on the used
39 * collation. if the field is set to binary, then a LIKE condition will also
40 * be case sensitive and when a case insensitive collation is used, the =
41 * operator will also be case insensitive.
43 * @param string|\Drupal\Core\Database\Query\ConditionInterface $field
44 * The name of the field to check. This can also be QueryConditionInterface
45 * in itself. Use where(), if you would like to add a more complex condition
46 * involving operators or functions, or an already compiled condition.
47 * @param string|array|\Drupal\Core\Database\Query\SelectInterface|null $value
48 * The value to test the field against. In most cases, and depending on the
49 * operator, this will be a scalar or an array. As SQL accepts select
50 * queries on any place where a scalar value or set is expected, $value may
51 * also be a(n array of) SelectInterface(s). If $operator is a unary
52 * operator, e.g. IS NULL, $value will be ignored and should be null. If
53 * the operator requires a subquery, e.g. EXISTS, the $field will be ignored
54 * and $value should be a SelectInterface object.
55 * @param string|null $operator
56 * The operator to use. Supported for all supported databases are at least:
57 * - The comparison operators =, <>, <, <=, >, >=.
58 * - The operators (NOT) BETWEEN, (NOT) IN, (NOT) EXISTS, (NOT) LIKE.
59 * Other operators (e.g. LIKE, BINARY) may or may not work. Defaults to =.
61 * @return \Drupal\Core\Database\Query\ConditionInterface
64 * @throws \Drupal\Core\Database\InvalidQueryException
65 * If passed invalid arguments, such as an empty array as $value.
67 * @see \Drupal\Core\Database\Query\ConditionInterface::isNull()
68 * @see \Drupal\Core\Database\Query\ConditionInterface::isNotNull()
69 * @see \Drupal\Core\Database\Query\ConditionInterface::exists()
70 * @see \Drupal\Core\Database\Query\ConditionInterface::notExist()
71 * @see \Drupal\Core\Database\Query\ConditionInterface::where()
73 public function condition($field, $value = NULL, $operator = '=');
76 * Adds an arbitrary WHERE clause to the query.
78 * @param string $snippet
79 * A portion of a WHERE clause as a prepared statement. It must use named
80 * placeholders, not ? placeholders. The caller is responsible for providing
81 * unique placeholders that do not interfere with the placeholders generated
82 * by this QueryConditionInterface object.
84 * An associative array of arguments keyed by the named placeholders.
86 * @return \Drupal\Core\Database\Query\ConditionInterface
89 public function where($snippet, $args = []);
92 * Sets a condition that the specified field be NULL.
94 * @param string|\Drupal\Core\Database\Query\SelectInterface $field
95 * The name of the field or a subquery to check.
97 * @return \Drupal\Core\Database\Query\ConditionInterface
100 public function isNull($field);
103 * Sets a condition that the specified field be NOT NULL.
105 * @param string|\Drupal\Core\Database\Query\SelectInterface $field
106 * The name of the field or a subquery to check.
108 * @return \Drupal\Core\Database\Query\ConditionInterface
111 public function isNotNull($field);
114 * Sets a condition that the specified subquery returns values.
116 * @param \Drupal\Core\Database\Query\SelectInterface $select
117 * The subquery that must contain results.
119 * @return \Drupal\Core\Database\Query\ConditionInterface
122 public function exists(SelectInterface $select);
125 * Sets a condition that the specified subquery returns no values.
127 * @param \Drupal\Core\Database\Query\SelectInterface $select
128 * The subquery that must not contain results.
130 * @return \Drupal\Core\Database\Query\ConditionInterface
133 public function notExists(SelectInterface $select);
136 * Gets the, possibly nested, list of conditions in this conditional clause.
138 * This method returns by reference. That allows alter hooks to access the
139 * data structure directly and manipulate it before it gets compiled.
141 * The data structure that is returned is an indexed array of entries, where
142 * each entry looks like the following:
147 * 'operator' => $operator,
151 * In the special case that $operator is NULL, the $field is taken as a raw
152 * SQL snippet (possibly containing a function) and $value is an associative
153 * array of placeholders for the snippet.
155 * There will also be a single array entry of #conjunction, which is the
156 * conjunction that will be applied to the array, such as AND.
159 * The, possibly nested, list of all conditions (by reference).
161 public function &conditions();
164 * Gets a complete list of all values to insert into the prepared statement.
167 * An associative array of placeholders and values.
169 public function arguments();
172 * Compiles the saved conditions for later retrieval.
174 * This method does not return anything, but simply prepares data to be
175 * retrieved via __toString() and arguments().
178 * The database connection for which to compile the conditionals.
179 * @param $queryPlaceholder
180 * The query this condition belongs to. If not given, the current query is
183 public function compile(Connection $connection, PlaceholderInterface $queryPlaceholder);
186 * Check whether a condition has been previously compiled.
189 * TRUE if the condition has been previously compiled.
191 public function compiled();
194 * Creates an object holding a group of conditions.
196 * See andConditionGroup() and orConditionGroup() for more.
198 * @param $conjunction
199 * - AND (default): this is the equivalent of andConditionGroup().
200 * - OR: this is the equivalent of orConditionGroup().
202 * @return \Drupal\Core\Database\Query\ConditionInterface
203 * An object holding a group of conditions.
205 public function conditionGroupFactory($conjunction = 'AND');
208 * Creates a new group of conditions ANDed together.
210 * @return \Drupal\Core\Database\Query\ConditionInterface
212 public function andConditionGroup();
215 * Creates a new group of conditions ORed together.
217 * @return \Drupal\Core\Database\Query\ConditionInterface
219 public function orConditionGroup();