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

Condition

class Condition implements ConditionInterface, Countable (View source)

Generic class for a series of conditions in a query.

Properties

static protected $conditionOperatorMap

Provides a map of condition operators to condition operator options.
protected array $conditions

Array of conditions.
protected array $arguments

Array of arguments.
protected bool $changed

Whether the conditions have been changed.
protected string $queryPlaceholderIdentifier

The identifier of the query placeholder this condition has been compiled against.
protected string $stringVersion

Contains the string version of the Condition.

Methods

__construct(string $conjunction, bool $trigger_deprecation = TRUE) deprecated

Constructs a Condition object.

count()

Implements Countable::count().

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

string
__toString()

Implements PHP magic __toString method to convert the conditions to string.

__clone()

PHP magic __clone() method.

array
mapConditionOperator(string $operator)

Gets any special processing requirements for the condition operator.

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 89
__construct(string $conjunction, bool $trigger_deprecation = TRUE) deprecated

deprecated in drupal:9.1.0 and is removed from drupal:10.0.0. Creating an instance of this class is deprecated.

Constructs a Condition object.

Parameters

string $conjunction

The operator to use to combine conditions: 'AND' or 'OR'.
bool $trigger_deprecation

If TRUE then trigger the deprecation warning.

See also

https://www.drupal.org/node/3159568

at line 104
count()

Implements Countable::count().

Returns the size of this conditional. The size of the conditional is the size of its conditional array minus one, because one element is the conjunction.

at line 112
$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 ANDs and ORs.

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 SelectInterface or an array of SelectInterfaces. 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

at line 134
$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 148
$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 155
$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 162
$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 169
$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 176
$this alwaysFalse()

Sets a condition that is always false.

Return Value

$this

at line 183
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 190
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 201
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 341
true compiled()

Check whether a condition has been previously compiled.

Return Value

true

if the condition has been previously compiled.

at line 351
string __toString()

Implements PHP magic __toString method to convert the conditions to string.

Return Value

string

A string version of the conditions.

at line 365
__clone()

PHP magic __clone() method.

Only copies fields that implement Drupal\Core\Database\Query\ConditionInterface. Also sets $this->changed to TRUE.

at line 393
protected array mapConditionOperator(string $operator)

Gets any special processing requirements for the condition operator.

Some condition types require special processing, such as IN, because the value data they pass in is not a simple value. This is a simple overridable lookup function.

Parameters

string $operator

The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.

Return Value

array

The extra handling directives for the specified operator or an empty array if there are no extra handling directives.

at line 413
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 420
ConditionInterface andConditionGroup()

Creates a new group of conditions ANDed together.

Return Value

ConditionInterface

at line 427
ConditionInterface orConditionGroup()

Creates a new group of conditions ORed together.

Return Value

ConditionInterface