123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221 |
- <?php
- namespace Drupal\Core\Database\Query;
- use Drupal\Core\Database\Connection;
- /**
- * Interface for a conditional clause in a query.
- */
- interface ConditionInterface {
- /**
- * Helper function: builds the most common conditional clauses.
- *
- * This method takes 1 to 3 parameters.
- *
- * If called with 1 parameter, it should be a ConditionInterface that in
- * itself forms a valid where clause. Use e.g. to build clauses with nested
- * AND's and OR's.
- *
- * If called with 2 parameters, they are taken as $field and $value with
- * $operator having a value of =.
- *
- * Do not use this method to test for NULL values. Instead, use
- * QueryConditionInterface::isNull() or QueryConditionInterface::isNotNull().
- *
- * To improve readability, the operators EXISTS and NOT EXISTS have their own
- * utility method defined.
- *
- * Drupal considers LIKE case insensitive and the following is often used
- * to tell the database that case insensitive equivalence is desired:
- * @code
- * db_select('users')
- * ->condition('name', db_like($name), 'LIKE')
- * @endcode
- * Use 'LIKE BINARY' instead of 'LIKE' for case sensitive queries.
- *
- * Note: When using MySQL, the exact behavior also depends on the used
- * collation. if the field is set to binary, then a LIKE condition will also
- * be case sensitive and when a case insensitive collation is used, the =
- * operator will also be case insensitive.
- *
- * @param string|\Drupal\Core\Database\Query\ConditionInterface $field
- * The name of the field to check. This can also be QueryConditionInterface
- * in itself. Use where(), if you would like to add a more complex condition
- * involving operators or functions, or an already compiled condition.
- * @param string|array|\Drupal\Core\Database\Query\SelectInterface|null $value
- * The value to test the field against. In most cases, and depending on the
- * operator, this will be a scalar or an array. As SQL accepts select
- * queries on any place where a scalar value or set is expected, $value may
- * also be a(n array of) SelectInterface(s). If $operator is a unary
- * operator, e.g. IS NULL, $value will be ignored and should be null. If
- * the operator requires a subquery, e.g. EXISTS, the $field will be ignored
- * and $value should be a SelectInterface object.
- * @param string|null $operator
- * The operator to use. Supported for all supported databases are at least:
- * - The comparison operators =, <>, <, <=, >, >=.
- * - The operators (NOT) BETWEEN, (NOT) IN, (NOT) EXISTS, (NOT) LIKE.
- * Other operators (e.g. LIKE, BINARY) may or may not work. Defaults to =.
- *
- * @return \Drupal\Core\Database\Query\ConditionInterface
- * The called object.
- *
- * @throws \Drupal\Core\Database\InvalidQueryException
- * If passed invalid arguments, such as an empty array as $value.
- *
- * @see \Drupal\Core\Database\Query\ConditionInterface::isNull()
- * @see \Drupal\Core\Database\Query\ConditionInterface::isNotNull()
- * @see \Drupal\Core\Database\Query\ConditionInterface::exists()
- * @see \Drupal\Core\Database\Query\ConditionInterface::notExist()
- * @see \Drupal\Core\Database\Query\ConditionInterface::where()
- */
- public function condition($field, $value = NULL, $operator = '=');
- /**
- * Adds an arbitrary WHERE clause to the query.
- *
- * @param string $snippet
- * A portion of a WHERE clause as a prepared statement. It must use named
- * placeholders, not ? placeholders. The caller is responsible for providing
- * unique placeholders that do not interfere with the placeholders generated
- * by this QueryConditionInterface object.
- * @param array $args
- * An associative array of arguments keyed by the named placeholders.
- *
- * @return \Drupal\Core\Database\Query\ConditionInterface
- * The called object.
- */
- public function where($snippet, $args = []);
- /**
- * Sets a condition that the specified field be NULL.
- *
- * @param string|\Drupal\Core\Database\Query\SelectInterface $field
- * The name of the field or a subquery to check.
- *
- * @return \Drupal\Core\Database\Query\ConditionInterface
- * The called object.
- */
- public function isNull($field);
- /**
- * Sets a condition that the specified field be NOT NULL.
- *
- * @param string|\Drupal\Core\Database\Query\SelectInterface $field
- * The name of the field or a subquery to check.
- *
- * @return \Drupal\Core\Database\Query\ConditionInterface
- * The called object.
- */
- public function isNotNull($field);
- /**
- * Sets a condition that the specified subquery returns values.
- *
- * @param \Drupal\Core\Database\Query\SelectInterface $select
- * The subquery that must contain results.
- *
- * @return \Drupal\Core\Database\Query\ConditionInterface
- * The called object.
- */
- public function exists(SelectInterface $select);
- /**
- * Sets a condition that the specified subquery returns no values.
- *
- * @param \Drupal\Core\Database\Query\SelectInterface $select
- * The subquery that must not contain results.
- *
- * @return \Drupal\Core\Database\Query\ConditionInterface
- * The called object.
- */
- public function notExists(SelectInterface $select);
- /**
- * Gets the, possibly nested, list of conditions in this conditional clause.
- *
- * This method returns by reference. That allows alter hooks to access the
- * data structure directly and manipulate it before it gets compiled.
- *
- * The data structure that is returned is an indexed array of entries, where
- * each entry looks like the following:
- * @code
- * array(
- * 'field' => $field,
- * 'value' => $value,
- * 'operator' => $operator,
- * );
- * @endcode
- *
- * In the special case that $operator is NULL, the $field is taken as a raw
- * SQL snippet (possibly containing a function) and $value is an associative
- * array of placeholders for the snippet.
- *
- * There will also be a single array entry of #conjunction, which is the
- * conjunction that will be applied to the array, such as AND.
- *
- * @return array
- * The, possibly nested, list of all conditions (by reference).
- */
- public function &conditions();
- /**
- * Gets a complete list of all values to insert into the prepared statement.
- *
- * @return
- * An associative array of placeholders and values.
- */
- public function arguments();
- /**
- * Compiles the saved conditions for later retrieval.
- *
- * This method does not return anything, but simply prepares data to be
- * retrieved via __toString() and arguments().
- *
- * @param $connection
- * The database connection for which to compile the conditionals.
- * @param $queryPlaceholder
- * The query this condition belongs to. If not given, the current query is
- * used.
- */
- public function compile(Connection $connection, PlaceholderInterface $queryPlaceholder);
- /**
- * Check whether a condition has been previously compiled.
- *
- * @return
- * TRUE if the condition has been previously compiled.
- */
- public function compiled();
- /**
- * Creates an object holding a group of conditions.
- *
- * See andConditionGroup() and orConditionGroup() for more.
- *
- * @param $conjunction
- * - AND (default): this is the equivalent of andConditionGroup().
- * - OR: this is the equivalent of orConditionGroup().
- *
- * @return \Drupal\Core\Database\Query\ConditionInterface
- * An object holding a group of conditions.
- */
- public function conditionGroupFactory($conjunction = 'AND');
- /**
- * Creates a new group of conditions ANDed together.
- *
- * @return \Drupal\Core\Database\Query\ConditionInterface
- */
- public function andConditionGroup();
- /**
- * Creates a new group of conditions ORed together.
- *
- * @return \Drupal\Core\Database\Query\ConditionInterface
- */
- public function orConditionGroup();
- }
|