This represents an SQL aggregate function expression in an SQL statement. Calls can be constructed by passing the name of the function and a list of params. For security reasons, all params passed are quoted by default unless explicitly told otherwise.
string
'FOLLOWING'
string
'GROUPS'
string
'PRECEDING'
string
'RANGE'
string
'ROWS'
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.
string
The name of the function to be constructed when generating the SQL string
string
The type name this expression will return when executed
Cake\Database\TypeMap|null
Cake\Database\Expression\QueryExpression
Cake\Database\Expression\WindowExpression
Clone this object and its subtree of expressions.
Constructor. Takes a name for the function to be invoked and a list of params to be passed into the function. Optionally you can pass a list of types to be used for each bound param.
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.
Returns the type name for the passed field if it was stored in the typeMap
Conditionally converts the passed value to an ExpressionInterface object if the type class implements the ExpressionTypeInterface. Otherwise, returns the value unmodified.
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.
Returns an array with the types that require values to be casted to expressions, out of the list of type names passed as parameter.
Adds one or more arguments for the function call.
Adds a new case expression to the expression object
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".
Returns a new case expression object.
The name of the function is in itself an expression to generate, thus always adding 1 to the amount of expressions stored in this object.
Adds a new condition to the expression object in the form "field = value".
Builds equal condition or assignment with identifier wrapping.
Adds current row frame exclusion.
Adds group frame exclusion.
Adds ties frame exclusion.
Adds a new condition to the expression object in the form "EXISTS (...)".
Adds conditions to the FILTER clause. The conditions are the same format as Query::where()
.
Adds a frame to the window.
Gets the currently configured conjunction for the conditions at this level of the expression tree.
Gets default types of current type map.
Gets the name of the SQL function to be invoke in this expression.
Gets the type of the value this object will generate.
Returns the existing type map.
Adds a simple groups frame to the window.
Adds a new condition to the expression object in the form "field > value".
Adds a new condition to the expression object in the form "field >= value".
Returns true if this expression contains any other nested ExpressionInterface objects
Adds a new condition to the expression object in the form "field IN (value1, value2)".
Check whether a callable is acceptable.
Adds a new condition to the expression object in the form "field IS NOT NULL".
Adds a new condition to the expression object in the form "field IS NULL".
Executes a callable function for each of the parts that form this expression.
Adds a new condition to the expression object in the form "field LIKE value".
Adds a new condition to the expression object in the form "field < value".
Adds a new condition to the expression object in the form "field <= value".
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 != value".
Adds a new condition to the expression object in the form "NOT EXISTS (...)".
Adds a new condition to the expression object in the form "field NOT IN (value1, value2)".
Adds a new condition to the expression object in the form "(field NOT IN (value1, value2) OR field IS NULL".
Adds a new condition to the expression object in the form "field NOT LIKE value".
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"
Adds one or more order clauses to the window.
Adds an empty OVER()
window expression or a named window epression.
Adds one or more partition expressions to the window.
Adds a simple range frame to the window.
Adds a simple rows frame to the window.
Changes the conjunction for the conditions at this level of the expression tree.
Overwrite the default type mappings for fields in the implementing object.
Sets the name of the SQL function to be invoke in this expression.
Sets the type of the value this object will generate.
Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.
Converts the Node into a SQL string fragment.
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.
__clone(): void
Clone this object and its subtree of expressions.
void
__construct(string $name, array $params = [], array<string, string>|array<string|null> $types = [], string $returnType = 'string')
Constructor. Takes a name for the function to be invoked and a list of params to be passed into the function. Optionally you can pass a list of types to be used for each bound param.
By default, all params that are passed will be quoted. If you wish to use literal arguments, you need to explicitly hint this function.
$f = new FunctionExpression('CONCAT', ['CakePHP', ' rules']);
Previous line will generate CONCAT('CakePHP', ' rules')
$f = new FunctionExpression('CONCAT', ['name' => 'literal', ' rules']);
Will produce CONCAT(name, ' rules')
string
$name the name of the function to be constructed
array
$params optional list of arguments to be passed to the function If associative the key would be used as argument when value is 'literal'
array<string, string>|array<string|null>
$types optional Associative array of types to be associated with the passed arguments
string
$returnType optional The return type of this expression
_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.
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
void
_calculateType(Cake\Database\ExpressionInterface|string $field): string|null
Returns the type name for the passed field if it was stored in the typeMap
Cake\Database\ExpressionInterface|string
$field The field name to get a type for.
string|null
_castToExpression(mixed $value, string|null $type = null): mixed
Conditionally converts the passed value to an ExpressionInterface object if the type class implements the ExpressionTypeInterface. Otherwise, returns the value unmodified.
mixed
$value The value to convert to ExpressionInterface
string|null
$type optional The type name
mixed
_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.
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
Cake\Database\ExpressionInterface
InvalidArgumentException
_requiresToExpressionCasting(array $types): array
Returns an array with the types that require values to be casted to expressions, out of the list of type names passed as parameter.
array
$types List of type names
array
add(array $conditions, array<string, string> $types = [], bool $prepend = false): $this
Adds one or more arguments for the function call.
array
$conditions list of arguments to be passed to the function If associative the key would be used as argument when value is 'literal'
array<string, string>
$types optional Associative array of types to be associated with the passed arguments
bool
$prepend optional Whether to prepend or append to the list of arguments
$this
addCase(Cake\Database\ExpressionInterface|array $conditions, Cake\Database\ExpressionInterface|array $values = [], array<string> $types = []): $this
Adds a new case expression to the expression object
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
$this
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"
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.
Cake\Database\Expression\QueryExpression
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"
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.
Cake\Database\Expression\QueryExpression
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".
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.
$this
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!
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.
Cake\Database\Expression\CaseStatementExpression
count(): int
The name of the function is in itself an expression to generate, thus always adding 1 to the amount of expressions stored in this object.
int
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".
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.
$this
equalFields(string $leftField, string $rightField): $this
Builds equal condition or assignment with identifier wrapping.
string
$leftField Left join condition field name.
string
$rightField Right join condition field name.
$this
excludeCurrent(): $this
Adds current row frame exclusion.
$this
excludeGroup(): $this
Adds group frame exclusion.
$this
excludeTies(): $this
Adds ties frame exclusion.
$this
exists(Cake\Database\ExpressionInterface $expression): $this
Adds a new condition to the expression object in the form "EXISTS (...)".
Cake\Database\ExpressionInterface
$expression the inner query
$this
filter(Cake\Database\ExpressionInterfaceClosure|array|string $conditions, array<string, string> $types = []): $this
Adds conditions to the FILTER clause. The conditions are the same format as Query::where()
.
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions The conditions to filter on.
array<string, string>
$types optional Associative array of type names used to bind values to query
$this
frame(string $type, Cake\Database\ExpressionInterface|string|int|null $startOffset, string $startDirection, Cake\Database\ExpressionInterface|string|int|null $endOffset, string $endDirection): $this
Adds a frame to the window.
Use the range()
, rows()
or groups()
helpers if you need simple 'BETWEEN offset PRECEDING and offset FOLLOWING' frames.
You can specify any direction for both frame start and frame end.
With both $startOffset
and $endOffset
:
0
- 'CURRENT ROW'null
- 'UNBOUNDED'string
$type Cake\Database\ExpressionInterface|string|int|null
$startOffset string
$startDirection Cake\Database\ExpressionInterface|string|int|null
$endOffset string
$endDirection $this
getConjunction(): string
Gets the currently configured conjunction for the conditions at this level of the expression tree.
string
getDefaultTypes(): array<int|string, string>
Gets default types of current type map.
array<int|string, string>
getName(): string
Gets the name of the SQL function to be invoke in this expression.
string
getReturnType(): string
Gets the type of the value this object will generate.
string
getTypeMap(): Cake\Database\TypeMap
Returns the existing type map.
Cake\Database\TypeMap
groups(int|null $start, int|null $end = 0): $this
Adds a simple groups frame to the window.
See range()
for details.
int|null
$start int|null
$end optional $this
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".
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.
$this
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".
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.
$this
hasNestedExpression(): bool
Returns true if this expression contains any other nested ExpressionInterface objects
bool
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)".
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.
$this
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.
Cake\Database\ExpressionInterface|callable|array|string
$callable The callable to check.
bool
isNotNull(Cake\Database\ExpressionInterface|string $field): $this
Adds a new condition to the expression object in the form "field IS NOT NULL".
Cake\Database\ExpressionInterface|string
$field database field to be tested for not null
$this
isNull(Cake\Database\ExpressionInterface|string $field): $this
Adds a new condition to the expression object in the form "field IS NULL".
Cake\Database\ExpressionInterface|string
$field database field to be tested for null
$this
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.
callable
$callback The callable to apply to each part.
$this
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".
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.
$this
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".
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.
$this
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".
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.
$this
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.
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.
$this
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".
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.
$this
notExists(Cake\Database\ExpressionInterface $expression): $this
Adds a new condition to the expression object in the form "NOT EXISTS (...)".
Cake\Database\ExpressionInterface
$expression the inner query
$this
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)".
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.
$this
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".
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.
$this
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".
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.
$this
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"
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.
Cake\Database\Expression\QueryExpression
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"
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.
Cake\Database\Expression\QueryExpression
order(Cake\Database\ExpressionInterfaceClosure|arrayCake\Database\ExpressionInterface|string>|string $fields): $this
Adds one or more order clauses to the window.
Cake\Database\ExpressionInterfaceClosure|arrayCake\Database\ExpressionInterface|string>|string
$fields $this
over(string|null $name = null): $this
Adds an empty OVER()
window expression or a named window epression.
string|null
$name optional Window name
$this
partition(Cake\Database\ExpressionInterfaceClosure|arrayCake\Database\ExpressionInterface|string>|string $partitions): $this
Adds one or more partition expressions to the window.
Cake\Database\ExpressionInterfaceClosure|arrayCake\Database\ExpressionInterface|string>|string
$partitions $this
range(Cake\Database\ExpressionInterface|string|int|null $start, Cake\Database\ExpressionInterface|string|int|null $end = 0): $this
Adds a simple range frame to the window.
$start
:
0
- 'CURRENT ROW'null
- 'UNBOUNDED PRECEDING'$end
:
0
- 'CURRENT ROW'null
- 'UNBOUNDED FOLLOWING'If you need to use 'FOLLOWING' with frame start or 'PRECEDING' with frame end, use frame()
instead.
Cake\Database\ExpressionInterface|string|int|null
$start Cake\Database\ExpressionInterface|string|int|null
$end optional $this
rows(int|null $start, int|null $end = 0): $this
Adds a simple rows frame to the window.
See range()
for details.
int|null
$start int|null
$end optional $this
setConjunction(string $conjunction): $this
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<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()
array<int|string, string>
$types The array of types to set.
$this
setName(string $name): $this
Sets the name of the SQL function to be invoke in this expression.
string
$name The name of the function
$this
setReturnType(string $type): $this
Sets the type of the value this object will generate.
string
$type The name of the type that is to be returned
$this
setTypeMap(Cake\Database\TypeMap|array $typeMap): $this
Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.
Cake\Database\TypeMap|array
$typeMap Creates a TypeMap if array, otherwise sets the given TypeMap
$this
sql(Cake\Database\ValueBinder $binder): string
Converts the Node into a SQL string fragment.
Cake\Database\ValueBinder
$binder string
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.
Closure
$callback $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
The name of the function to be constructed when generating the SQL string
string
The type name this expression will return when executed
string
Cake\Database\TypeMap|null
Cake\Database\Expression\QueryExpression
Cake\Database\Expression\WindowExpression
© 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.4/class-Cake.Database.Expression.AggregateExpression.html