Class QueryExpression

Represents a SQL Query expression. Internally it stores a tree of expressions that can be compiled by converting this object to string and will contain a correctly parenthesized and nested expression.

Namespace: Cake\Database\Expression

Property Summary

$_conditions protected

array

A list of strings or other expression objects that represent the "branches" of the expression tree. For example one key of the array might look like "sum > :value"
$_conjunction protected

string

String to be used for joining each of the internal expressions this object internally stores for example "AND", "OR", etc.
$_typeMap protected

Cake\Database\TypeMap|null

Method Summary

__clone() public

Clone this object and its subtree of expressions.
__construct() public

Constructor. A new expression object can be created without any params and be built dynamically. Otherwise, it is possible to pass an array of conditions containing either a tree-like array structure to be parsed and/or other expression objects. Optionally, you can set the conjunction keyword to be used for joining each part of this level of the expression tree.
_addConditions() protected

Auxiliary function used for decomposing a nested array of conditions and build a tree structure inside this object to represent the full SQL expression. String conditions are stored directly in the conditions, while any other representation is wrapped around an adequate instance or of this class.
_calculateType() protected

Returns the type name for the passed field if it was stored in the typeMap
_parseCondition() protected

Parses a string conditions by trying to extract the operator inside it if any and finally returning either an adequate QueryExpression object or a plain string representation of the condition. This function is responsible for generating the placeholders and replacing the values by them, while storing the value elsewhere for future binding.
add() public

Adds one or more conditions to this expression object. Conditions can be expressed in a one dimensional array, that will cause all conditions to be added directly at this level of the tree or they can be nested arbitrarily making it create more expression objects that will be nested inside and configured to use the specified conjunction.
addCase() public deprecated

Adds a new case expression to the expression object
and() public

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"
and_() public deprecated

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"
between() public

Adds a new condition to the expression object in the form "field BETWEEN from AND to".
case() public

Returns a new case expression object.
count() public

Returns the number of internal conditions that are stored in this expression. Useful to determine if this expression object is void or it will generate a non-empty string when compiled
eq() public

Adds a new condition to the expression object in the form "field = value".
equalFields() public

Builds equal condition or assignment with identifier wrapping.
exists() public

Adds a new condition to the expression object in the form "EXISTS (...)".
getConjunction() public

Gets the currently configured conjunction for the conditions at this level of the expression tree.
getDefaultTypes() public

Gets default types of current type map.
getTypeMap() public

Returns the existing type map.
gt() public

Adds a new condition to the expression object in the form "field > value".
gte() public

Adds a new condition to the expression object in the form "field >= value".
hasNestedExpression() public

Returns true if this expression contains any other nested ExpressionInterface objects
in() public

Adds a new condition to the expression object in the form "field IN (value1, value2)".
isCallable() public deprecated

Check whether a callable is acceptable.
isNotNull() public

Adds a new condition to the expression object in the form "field IS NOT NULL".
isNull() public

Adds a new condition to the expression object in the form "field IS NULL".
iterateParts() public

Executes a callable function for each of the parts that form this expression.
like() public

Adds a new condition to the expression object in the form "field LIKE value".
lt() public

Adds a new condition to the expression object in the form "field < value".
lte() public

Adds a new condition to the expression object in the form "field <= value".
not() public

Adds a new set of conditions to this level of the tree and negates the final result by prepending a NOT, it will look like "NOT ( (condition1) AND (conditions2) )" conjunction depends on the one currently configured for this object.
notEq() public

Adds a new condition to the expression object in the form "field != value".
notExists() public

Adds a new condition to the expression object in the form "NOT EXISTS (...)".
notIn() public

Adds a new condition to the expression object in the form "field NOT IN (value1, value2)".
notInOrNull() public

Adds a new condition to the expression object in the form "(field NOT IN (value1, value2) OR field IS NULL".
notLike() public

Adds a new condition to the expression object in the form "field NOT LIKE value".
or() public

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"
or_() public deprecated

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"
setConjunction() public

Changes the conjunction for the conditions at this level of the expression tree.
setDefaultTypes() public

Overwrite the default type mappings for fields in the implementing object.
setTypeMap() public

Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.
sql() public

Converts the Node into a SQL string fragment.
traverse() public

Iterates over each part of the expression recursively for every level of the expressions tree and executes the $callback callable passing as first parameter the instance of the expression currently being iterated.

Method Detail

__clone() ¶ public

__clone(): void

Clone this object and its subtree of expressions.

Returns

void

__construct() ¶ public

__construct(Cake\Database\ExpressionInterface|array|string $conditions = [], Cake\Database\TypeMap|array $types = [], string $conjunction = 'AND')

Constructor. A new expression object can be created without any params and be built dynamically. Otherwise, it is possible to pass an array of conditions containing either a tree-like array structure to be parsed and/or other expression objects. Optionally, you can set the conjunction keyword to be used for joining each part of this level of the expression tree.

Parameters

Cake\Database\ExpressionInterface|array|string $conditions optional: Tree like array structure containing all the conditions to be added or nested inside this expression object.
Cake\Database\TypeMap|array $types optional: Associative array of types to be associated with the values passed in $conditions.
string $conjunction optional: the glue that will join all the string conditions at this level of the expression tree. For example "AND", "OR", "XOR"...

_addConditions() ¶ protected

_addConditions(array $conditions, array<int|string, string> $types): void

Auxiliary function used for decomposing a nested array of conditions and build a tree structure inside this object to represent the full SQL expression. String conditions are stored directly in the conditions, while any other representation is wrapped around an adequate instance or of this class.

Parameters

array $conditions: list of conditions to be stored in this object
array<int|string, string> $types: list of types associated on fields referenced in $conditions

Returns

void

_calculateType() ¶ protected

_calculateType(Cake\Database\ExpressionInterface|string $field): string|null

Returns the type name for the passed field if it was stored in the typeMap

Parameters

Cake\Database\ExpressionInterface|string $field: The field name to get a type for.

Returns

string|null

_parseCondition() ¶ protected

_parseCondition(string $field, mixed $value): Cake\Database\ExpressionInterface

Parses a string conditions by trying to extract the operator inside it if any and finally returning either an adequate QueryExpression object or a plain string representation of the condition. This function is responsible for generating the placeholders and replacing the values by them, while storing the value elsewhere for future binding.

Parameters

string $field: The value from which the actual field and operator will be extracted.
mixed $value: The value to be bound to a placeholder for the field

Returns

Cake\Database\ExpressionInterface

Throws

InvalidArgumentException
If operator is invalid or missing on NULL usage.

add() ¶ public

add(Cake\Database\ExpressionInterface|array|string $conditions, array<int|string, string> $types = []): $this

Adds one or more conditions to this expression object. Conditions can be expressed in a one dimensional array, that will cause all conditions to be added directly at this level of the tree or they can be nested arbitrarily making it create more expression objects that will be nested inside and configured to use the specified conjunction.

If the type passed for any of the fields is expressed "type[]" (note braces) then it will cause the placeholder to be re-written dynamically so if the value is an array, it will create as many placeholders as values are in it.

Parameters

Cake\Database\ExpressionInterface|array|string $conditions: single or multiple conditions to be added. When using an array and the key is 'OR' or 'AND' a new expression object will be created with that conjunction and internal array value passed as conditions.
array<int|string, string> $types optional: Associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns

$this

addCase() ¶ public

addCase(Cake\Database\ExpressionInterface|array $conditions, Cake\Database\ExpressionInterface|array $values = [], array<string> $types = []): $this

Adds a new case expression to the expression object

Parameters

Cake\Database\ExpressionInterface|array $conditions: The conditions to test. Must be a ExpressionInterface instance, or an array of ExpressionInterface instances.
Cake\Database\ExpressionInterface|array $values optional: Associative array of values to be associated with the conditions passed in $conditions. If there are more $values than $conditions, the last $value is used as the ELSE value.
array<string> $types optional: Associative array of types to be associated with the values passed in $values

Returns

$this

and() ¶ public

and(Cake\Database\ExpressionInterfaceClosure|array|string $conditions, array<string, string> $types = []): Cake\Database\Expression\QueryExpression

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"

Parameters

Cake\Database\ExpressionInterfaceClosure|array|string $conditions: to be joined with AND
array<string, string> $types optional: Associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns

Cake\Database\Expression\QueryExpression

and_() ¶ public

and_(Cake\Database\ExpressionInterfaceClosure|array|string $conditions, array<string, string> $types = []): Cake\Database\Expression\QueryExpression

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"

Parameters

Cake\Database\ExpressionInterfaceClosure|array|string $conditions: to be joined with AND
array<string, string> $types optional: Associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns

Cake\Database\Expression\QueryExpression

between() ¶ public

between(Cake\Database\ExpressionInterface|string $field, mixed $from, mixed $to, string|null $type = null): $this

Adds a new condition to the expression object in the form "field BETWEEN from AND to".

Parameters

Cake\Database\ExpressionInterface|string $field: The field name to compare for values inbetween the range.
mixed $from: The initial value of the range.
mixed $to: The ending value in the comparison range.
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

case() ¶ public

case(Cake\Database\ExpressionInterface|object|scalar|null $value = null, string|null $type = null): Cake\Database\Expression\CaseStatementExpression

Returns a new case expression object.

When a value is set, the syntax generated is CASE case_value WHEN when_value ... END (simple case), where the when_value's are compared against the case_value.

When no value is set, the syntax generated is CASE WHEN when_conditions ... END (searched case), where the conditions hold the comparisons.

Note that null is a valid case value, and thus should only be passed if you actually want to create the simple case expression variant!

Parameters

Cake\Database\ExpressionInterface|object|scalar|null $value optional: The case value.
string|null $type optional: The case value type. If no type is provided, the type will be tried to be inferred from the value.

Returns

Cake\Database\Expression\CaseStatementExpression

count() ¶ public

count(): int

Returns the number of internal conditions that are stored in this expression. Useful to determine if this expression object is void or it will generate a non-empty string when compiled

Returns

int

eq() ¶ public

eq(Cake\Database\ExpressionInterface|string $field, mixed $value, string|null $type = null): $this

Adds a new condition to the expression object in the form "field = value".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
mixed $value: The value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map. If it is suffixed with "[]" and the value is an array then multiple placeholders will be created, one per each value in the array.

Returns

$this

equalFields() ¶ public

equalFields(string $leftField, string $rightField): $this

Builds equal condition or assignment with identifier wrapping.

Parameters

string $leftField: Left join condition field name.
string $rightField: Right join condition field name.

Returns

$this

exists() ¶ public

exists(Cake\Database\ExpressionInterface $expression): $this

Adds a new condition to the expression object in the form "EXISTS (...)".

Parameters

Cake\Database\ExpressionInterface $expression: the inner query

Returns

$this

getConjunction() ¶ public

getConjunction(): string

Gets the currently configured conjunction for the conditions at this level of the expression tree.

Returns

string

getDefaultTypes() ¶ public

getDefaultTypes(): array<int|string, string>

Gets default types of current type map.

Returns

array<int|string, string>

getTypeMap() ¶ public

getTypeMap(): Cake\Database\TypeMap

Returns the existing type map.

Returns

Cake\Database\TypeMap

gt() ¶ public

gt(Cake\Database\ExpressionInterface|string $field, mixed $value, string|null $type = null): $this

Adds a new condition to the expression object in the form "field > value".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
mixed $value: The value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

gte() ¶ public

gte(Cake\Database\ExpressionInterface|string $field, mixed $value, string|null $type = null): $this

Adds a new condition to the expression object in the form "field >= value".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
mixed $value: The value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

hasNestedExpression() ¶ public

hasNestedExpression(): bool

Returns true if this expression contains any other nested ExpressionInterface objects

Returns

bool

in() ¶ public

in(Cake\Database\ExpressionInterface|string $field, Cake\Database\ExpressionInterface|array|string $values, string|null $type = null): $this

Adds a new condition to the expression object in the form "field IN (value1, value2)".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
Cake\Database\ExpressionInterface|array|string $values: the value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

isCallable() ¶ public

isCallable(Cake\Database\ExpressionInterface|callable|array|string $callable): bool

Check whether a callable is acceptable.

We don't accept ['class', 'method'] style callbacks, as they often contain user input and arrays of strings are easy to sneak in.

Parameters

Cake\Database\ExpressionInterface|callable|array|string $callable: The callable to check.

Returns

bool

isNotNull() ¶ public

isNotNull(Cake\Database\ExpressionInterface|string $field): $this

Adds a new condition to the expression object in the form "field IS NOT NULL".

Parameters

Cake\Database\ExpressionInterface|string $field: database field to be tested for not null

Returns

$this

isNull() ¶ public

isNull(Cake\Database\ExpressionInterface|string $field): $this

Adds a new condition to the expression object in the form "field IS NULL".

Parameters

Cake\Database\ExpressionInterface|string $field: database field to be tested for null

Returns

$this

iterateParts() ¶ public

iterateParts(callable $callback): $this

Executes a callable function for each of the parts that form this expression.

The callable function is required to return a value with which the currently visited part will be replaced. If the callable function returns null then the part will be discarded completely from this expression.

The callback function will receive each of the conditions as first param and the key as second param. It is possible to declare the second parameter as passed by reference, this will enable you to change the key under which the modified part is stored.

Parameters

callable $callback: The callable to apply to each part.

Returns

$this

like() ¶ public

like(Cake\Database\ExpressionInterface|string $field, mixed $value, string|null $type = null): $this

Adds a new condition to the expression object in the form "field LIKE value".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
mixed $value: The value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

lt() ¶ public

lt(Cake\Database\ExpressionInterface|string $field, mixed $value, string|null $type = null): $this

Adds a new condition to the expression object in the form "field < value".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
mixed $value: The value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

lte() ¶ public

lte(Cake\Database\ExpressionInterface|string $field, mixed $value, string|null $type = null): $this

Adds a new condition to the expression object in the form "field <= value".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
mixed $value: The value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

not() ¶ public

not(Cake\Database\ExpressionInterfaceClosure|array|string $conditions, array<string, string> $types = []): $this

Adds a new set of conditions to this level of the tree and negates the final result by prepending a NOT, it will look like "NOT ( (condition1) AND (conditions2) )" conjunction depends on the one currently configured for this object.

Parameters

Cake\Database\ExpressionInterfaceClosure|array|string $conditions: to be added and negated
array<string, string> $types optional: Associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns

$this

notEq() ¶ public

notEq(Cake\Database\ExpressionInterface|string $field, mixed $value, string|null $type = null): $this

Adds a new condition to the expression object in the form "field != value".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
mixed $value: The value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map. If it is suffixed with "[]" and the value is an array then multiple placeholders will be created, one per each value in the array.

Returns

$this

notExists() ¶ public

notExists(Cake\Database\ExpressionInterface $expression): $this

Adds a new condition to the expression object in the form "NOT EXISTS (...)".

Parameters

Cake\Database\ExpressionInterface $expression: the inner query

Returns

$this

notIn() ¶ public

notIn(Cake\Database\ExpressionInterface|string $field, Cake\Database\ExpressionInterface|array|string $values, string|null $type = null): $this

Adds a new condition to the expression object in the form "field NOT IN (value1, value2)".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
Cake\Database\ExpressionInterface|array|string $values: the value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

notInOrNull() ¶ public

notInOrNull(Cake\Database\ExpressionInterface|string $field, Cake\Database\ExpressionInterface|array|string $values, string|null $type = null): $this

Adds a new condition to the expression object in the form "(field NOT IN (value1, value2) OR field IS NULL".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
Cake\Database\ExpressionInterface|array|string $values: the value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

notLike() ¶ public

notLike(Cake\Database\ExpressionInterface|string $field, mixed $value, string|null $type = null): $this

Adds a new condition to the expression object in the form "field NOT LIKE value".

Parameters

Cake\Database\ExpressionInterface|string $field: Database field to be compared against value
mixed $value: The value to be bound to $field for comparison
string|null $type optional: the type name for $value as configured using the Type map.

Returns

$this

or() ¶ public

or(Cake\Database\ExpressionInterfaceClosure|array|string $conditions, array<string, string> $types = []): Cake\Database\Expression\QueryExpression

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"

Parameters

Cake\Database\ExpressionInterfaceClosure|array|string $conditions: to be joined with OR
array<string, string> $types optional: Associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns

Cake\Database\Expression\QueryExpression

or_() ¶ public

or_(Cake\Database\ExpressionInterfaceClosure|array|string $conditions, array<string, string> $types = []): Cake\Database\Expression\QueryExpression

Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"

Parameters

Cake\Database\ExpressionInterfaceClosure|array|string $conditions: to be joined with OR
array<string, string> $types optional: Associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.

Returns

Cake\Database\Expression\QueryExpression

setConjunction() ¶ public

setConjunction(string $conjunction): $this

Changes the conjunction for the conditions at this level of the expression tree.

Parameters

string $conjunction: Value to be used for joining conditions

Returns

$this

setDefaultTypes() ¶ public

setDefaultTypes(array<int|string, string> $types): $this

Overwrite the default type mappings for fields in the implementing object.

This method is useful if you need to set type mappings that are shared across multiple functions/expressions in a query.

To add a default without overwriting existing ones use getTypeMap()->addDefaults()

Parameters

array<int|string, string> $types: The array of types to set.

Returns

$this

setTypeMap() ¶ public

setTypeMap(Cake\Database\TypeMap|array $typeMap): $this

Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.

Parameters

Cake\Database\TypeMap|array $typeMap: Creates a TypeMap if array, otherwise sets the given TypeMap

Returns

$this

sql() ¶ public

sql(Cake\Database\ValueBinder $binder): string

Converts the Node into a SQL string fragment.

Parameters

Cake\Database\ValueBinder $binder

Returns

string

traverse() ¶ public

traverse(Closure $callback): $this

Iterates over each part of the expression recursively for every level of the expressions tree and executes the $callback callable passing as first parameter the instance of the expression currently being iterated.

Parameters

Closure $callback

Returns

$this

Property Detail

`$_conditions` ¶ protected

A list of strings or other expression objects that represent the "branches" of the expression tree. For example one key of the array might look like "sum > :value"

Type

array

`$_conjunction` ¶ protected

String to be used for joining each of the internal expressions this object internally stores for example "AND", "OR", etc.

Type

string

`$_typeMap` ¶ protected

Type

Cake\Database\TypeMap|null

Namespaces

Class QueryExpression

Property Summary

Method Summary

__clone() public

__construct() public

_addConditions() protected

_calculateType() protected

_parseCondition() protected

add() public

addCase() public deprecated

and() public

and_() public deprecated

between() public

case() public

count() public

eq() public

equalFields() public

exists() public

getConjunction() public

getDefaultTypes() public

getTypeMap() public

gt() public

gte() public

hasNestedExpression() public

in() public

isCallable() public deprecated

isNotNull() public

isNull() public

iterateParts() public

like() public

lt() public

lte() public

not() public

notEq() public

notExists() public

notIn() public

notInOrNull() public

notLike() public

or() public

or_() public deprecated

setConjunction() public

setDefaultTypes() public

setTypeMap() public

sql() public

traverse() public

Method Detail

__clone() ¶ public

Returns

__construct() ¶ public

Parameters

See Also

_addConditions() ¶ protected

Parameters

Returns

_calculateType() ¶ protected

Parameters

Returns

_parseCondition() ¶ protected

Parameters

Returns

Throws

add() ¶ public

Parameters

Returns

See Also

addCase() ¶ public

Parameters

Returns

and() ¶ public

Parameters

Returns

and_() ¶ public

Parameters

Returns

between() ¶ public

Parameters

Returns

case() ¶ public

Parameters