1. interface
  2. Drupal
  3. \
  4. Core
  5. \
  6. Database
  7. \
  8. Query
  9. \
  10. ConditionInterface

ConditionInterface

interface ConditionInterface (View source)

Interface for a conditional clause in a query.

Methods

$this
condition(string|ConditionInterface $field, string|array|SelectInterface|null $value = NULL, string|null $operator = '=')

Helper function: builds the most common conditional clauses.

$this
where(string $snippet, array $args = [])

Adds an arbitrary WHERE clause to the query.

$this
isNull(string|SelectInterface $field)

Sets a condition that the specified field be NULL.

$this
isNotNull(string|SelectInterface $field)

Sets a condition that the specified field be NOT NULL.

$this
exists(SelectInterface $select)

Sets a condition that the specified subquery returns values.

$this
notExists(SelectInterface $select)

Sets a condition that the specified subquery returns no values.

$this
alwaysFalse()

Sets a condition that is always false.

array
conditions()

Gets the, possibly nested, list of conditions in this conditional clause.

An
arguments()

Gets a complete list of all values to insert into the prepared statement.

compile(Connection $connection, PlaceholderInterface $queryPlaceholder)

Compiles the saved conditions for later retrieval.

true
compiled()

Check whether a condition has been previously compiled.

ConditionInterface
conditionGroupFactory($conjunction = 'AND')

Creates an object holding a group of conditions.

ConditionInterface
andConditionGroup()

Creates a new group of conditions ANDed together.

ConditionInterface
orConditionGroup()

Creates a new group of conditions ORed together.

Details

at line 73
$this condition(string|ConditionInterface $field, string|array|SelectInterface|null $value = NULL, string|null $operator = '=')

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:

Parameters

string|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.
string|array|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.
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 Value

$this

The called object.

Exceptions

InvalidQueryException

See also

ConditionInterface::isNull
ConditionInterface::isNotNull
ConditionInterface::exists
\Drupal\Core\Database\Query\ConditionInterface::notExist()
ConditionInterface::where

at line 89
$this where(string $snippet, array $args = [])

Adds an arbitrary WHERE clause to the query.

Parameters

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.
array $args

An associative array of arguments keyed by the named placeholders.

Return Value

$this

The called object.

at line 100
$this isNull(string|SelectInterface $field)

Sets a condition that the specified field be NULL.

Parameters

string|SelectInterface $field

The name of the field or a subquery to check.

Return Value

$this

The called object.

at line 111
$this isNotNull(string|SelectInterface $field)

Sets a condition that the specified field be NOT NULL.

Parameters

string|SelectInterface $field

The name of the field or a subquery to check.

Return Value

$this

The called object.

at line 122
$this exists(SelectInterface $select)

Sets a condition that the specified subquery returns values.

Parameters

SelectInterface $select

The subquery that must contain results.

Return Value

$this

The called object.

at line 133
$this notExists(SelectInterface $select)

Sets a condition that the specified subquery returns no values.

Parameters

SelectInterface $select

The subquery that must not contain results.

Return Value

$this

The called object.

at line 140
$this alwaysFalse()

Sets a condition that is always false.

Return Value

$this

at line 168
array conditions()

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:

Return Value

array

The, possibly nested, list of all conditions (by reference).

at line 176
An arguments()

Gets a complete list of all values to insert into the prepared statement.

Return Value

An

associative array of placeholders and values.

at line 190
compile(Connection $connection, PlaceholderInterface $queryPlaceholder)

Compiles the saved conditions for later retrieval.

This method does not return anything, but simply prepares data to be retrieved via __toString() and arguments().

Parameters

Connection $connection

The database connection for which to compile the conditionals.
PlaceholderInterface $queryPlaceholder

The query this condition belongs to. If not given, the current query is used.

at line 198
true compiled()

Check whether a condition has been previously compiled.

Return Value

true

if the condition has been previously compiled.

at line 212
ConditionInterface conditionGroupFactory($conjunction = 'AND')

Creates an object holding a group of conditions.

See andConditionGroup() and orConditionGroup() for more.

Parameters

$conjunction
  • AND (default): this is the equivalent of andConditionGroup().
  • OR: this is the equivalent of orConditionGroup().

Return Value

ConditionInterface

An object holding a group of conditions.

at line 219
ConditionInterface andConditionGroup()

Creates a new group of conditions ANDed together.

Return Value

ConditionInterface

at line 226
ConditionInterface orConditionGroup()

Creates a new group of conditions ORed together.

Return Value

ConditionInterface