Class OrderByExpression
An expression object for ORDER BY clauses
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
-
_addConditions() protected
Auxiliary function used for decomposing a nested array of conditions and building a tree structure inside this object to represent the full SQL expression.
-
_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
__construct() ¶ public
__construct(Cake\Database\ExpressionInterface|array|string $conditions = [], Cake\Database\TypeMap|array $types = [], string $conjunction = '')
Constructor
Parameters
-
Cake\Database\ExpressionInterface|array|string
$conditions optional The sort columns
-
Cake\Database\TypeMap|array
$types optional The types for each column.
-
string
$conjunction optional The glue used to join conditions together.
_addConditions() ¶ protected
_addConditions(array $conditions, array<string, string> $types): void
Auxiliary function used for decomposing a nested array of conditions and building a tree structure inside this object to represent the full SQL expression.
New order by expressions are merged to existing ones
Parameters
-
array
$conditions list of order by expressions
-
array<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<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<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
See Also
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<string, string>
Gets default types of current type map.
Returns
array<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<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<string, string>
$types The array of types to set.
Returns
$this
See Also
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