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.
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"
string
String to be used for joining each of the internal expressions this object internally stores for example "AND", "OR", etc.
\Cake\Database\TypeMap
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.
Auxiliary function used for decomposing a nested array of conditions and build a tree structure inside this object to represent the full SQL expression.
Returns the type name for the passed field if it was stored in the typeMap
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.
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.
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"
Adds a new condition to the expression object in the form "field BETWEEN from AND to".
Gets the currently configured conjunction for the conditions at this level of the expression tree.
Returns true if this expression contains any other nested ExpressionInterface objects
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.
Adds a new condition to the expression object in the form "field NOT IN (value1, value2)".
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"
Changes the conjunction for the conditions at this level of the expression tree.
Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.
Returns the string representation of this object so that it can be used in a SQL query. Note that values condition values are not included in the string, in their place placeholders are put and can be replaced by the quoted values accordingly.
Traverses the tree structure of this query expression by executing a callback function for each of the conditions that are included in this object.
__clone()
Clone this object and its subtree of expressions.
__construct(mixed $conditions, mixed $types, mixed $conjunction)
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.
string|array|\Cake\Database\ExpressionInterface
$conditions optional Tree like array structure containing all the conditions to be added or nested inside this expression object.
array|\Cake\Database\TypeMap
$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(array $conditions, array $types)
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.
array
$conditions list of conditions to be stored in this object
array
$types list of types associated on fields referenced in $conditions
_calculateType(mixed $field)
Returns the type name for the passed field if it was stored in the typeMap
string|\Cake\Database\ExpressionInterface
$field The field name to get a type for.
string|null
The computed type or null, if the type is unknown.
_parseCondition(string $field, mixed $value)
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.
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
string|\Cake\Database\ExpressionInterface
InvalidArgumentException
add(mixed $conditions, array $types)
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.
string|array|\Cake\Database\ExpressionInterface
$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
$types optional associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.
$this
addCase(mixed $conditions, mixed $values, mixed $types)
Adds a new case expression to the expression object
array|\Cake\Database\ExpressionInterface
$conditions The conditions to test. Must be a ExpressionInterface instance, or an array of ExpressionInterface instances.
array|\Cake\Database\ExpressionInterface
$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
$types optional associative array of types to be associated with the values passed in $values
$this
and(mixed $conditions, mixed $types)
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"
\Closure|string|array|\Cake\Database\ExpressionInterface
$conditions to be joined with AND
array
$types optional associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.
\Cake\Database\Expression\QueryExpression
and_(mixed $conditions, mixed $types)
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"
\Closure|string|array|\Cake\Database\ExpressionInterface
$conditions to be joined with AND
array
$types optional associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.
\Cake\Database\Expression\QueryExpression
between(mixed $field, mixed $from, mixed $to, mixed $type)
Adds a new condition to the expression object in the form "field BETWEEN from AND to".
string|\Cake\Database\ExpressionInterface
$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.
$this
count()
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
int
eq(mixed $field, mixed $value, ?string $type)
Adds a new condition to the expression object in the form "field = value".
string|\Cake\Database\ExpressionInterface
$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.
$this
equalFields(string $left, string $right)
Builds equal condition or assignment with identifier wrapping.
string
$left Left join condition field name.
string
$right Right join condition field name.
$this
exists(\Cake\Database\ExpressionInterface $query)
Adds a new condition to the expression object in the form "EXISTS (...)".
\Cake\Database\ExpressionInterface
$query the inner query
$this
getConjunction()
Gets the currently configured conjunction for the conditions at this level of the expression tree.
string
getDefaultTypes()
Gets default types of current type map.
array
getTypeMap()
Returns the existing type map.
\Cake\Database\TypeMap
gt(mixed $field, mixed $value, mixed $type)
Adds a new condition to the expression object in the form "field > value".
string|\Cake\Database\ExpressionInterface
$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.
$this
gte(mixed $field, mixed $value, mixed $type)
Adds a new condition to the expression object in the form "field >= value".
string|\Cake\Database\ExpressionInterface
$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.
$this
hasNestedExpression()
Returns true if this expression contains any other nested ExpressionInterface objects
bool
in(mixed $field, mixed $values, mixed $type)
Adds a new condition to the expression object in the form "field IN (value1, value2)".
string|\Cake\Database\ExpressionInterface
$field Database field to be compared against value
string|array|\Cake\Database\ExpressionInterface
$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.
$this
isCallable(mixed $c)
Check whether or not 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.
callable|string|array|\Cake\Database\ExpressionInterface
$c The callable to check.
bool
Valid callable.
isNotNull(mixed $field)
Adds a new condition to the expression object in the form "field IS NOT NULL".
string|\Cake\Database\ExpressionInterface
$field database field to be tested for not null
$this
isNull(mixed $field)
Adds a new condition to the expression object in the form "field IS NULL".
string|\Cake\Database\ExpressionInterface
$field database field to be tested for null
$this
iterateParts(callable $visitor)
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.
callable
$visitor The callable to apply to each part.
$this
like(mixed $field, mixed $value, mixed $type)
Adds a new condition to the expression object in the form "field LIKE value".
string|\Cake\Database\ExpressionInterface
$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.
$this
lt(mixed $field, mixed $value, mixed $type)
Adds a new condition to the expression object in the form "field < value".
string|\Cake\Database\ExpressionInterface
$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.
$this
lte(mixed $field, mixed $value, mixed $type)
Adds a new condition to the expression object in the form "field <= value".
string|\Cake\Database\ExpressionInterface
$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.
$this
not(mixed $conditions, mixed $types)
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.
string|array|\Cake\Database\ExpressionInterface
$conditions to be added and negated
array
$types optional associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.
$this
notEq(mixed $field, mixed $value, mixed $type)
Adds a new condition to the expression object in the form "field != value".
string|\Cake\Database\ExpressionInterface
$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.
$this
notExists(\Cake\Database\ExpressionInterface $query)
Adds a new condition to the expression object in the form "NOT EXISTS (...)".
\Cake\Database\ExpressionInterface
$query the inner query
$this
notIn(mixed $field, mixed $values, mixed $type)
Adds a new condition to the expression object in the form "field NOT IN (value1, value2)".
string|\Cake\Database\ExpressionInterface
$field Database field to be compared against value
array|\Cake\Database\ExpressionInterface
$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.
$this
notLike(mixed $field, mixed $value, mixed $type)
Adds a new condition to the expression object in the form "field NOT LIKE value".
string|\Cake\Database\ExpressionInterface
$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.
$this
or(mixed $conditions, mixed $types)
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"
\Closure|string|array|\Cake\Database\ExpressionInterface
$conditions to be joined with OR
array
$types optional associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.
\Cake\Database\Expression\QueryExpression
or_(mixed $conditions, mixed $types)
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"
\Closure|string|array|\Cake\Database\ExpressionInterface
$conditions to be joined with OR
array
$types optional associative array of fields pointing to the type of the values that are being passed. Used for correctly binding values to statements.
\Cake\Database\Expression\QueryExpression
setConjunction(string $conjunction)
Changes the conjunction for the conditions at this level of the expression tree.
string
$conjunction Value to be used for joining conditions
$this
setDefaultTypes(array $types)
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()
array
$types The array of types to set.
$this
setTypeMap(mixed $typeMap)
Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.
array|\Cake\Database\TypeMap
$typeMap Creates a TypeMap if array, otherwise sets the given TypeMap
$this
sql(\Cake\Database\ValueBinder $generator)
Returns the string representation of this object so that it can be used in a SQL query. Note that values condition values are not included in the string, in their place placeholders are put and can be replaced by the quoted values accordingly.
\Cake\Database\ValueBinder
$generator Placeholder generator object
string
traverse(\Closure $visitor)
Traverses the tree structure of this query expression by executing a callback function for each of the conditions that are included in this object.
Useful for compiling the final expression, or doing introspection in the structure.
Callback function receives as only argument an instance of ExpressionInterface
\Closure
$visitor The callable to apply to all sub-expressions.
$this
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"
array
String to be used for joining each of the internal expressions this object internally stores for example "AND", "OR", etc.
string
\Cake\Database\TypeMap
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.Database.Expression.QueryExpression.html