Class FunctionExpression

This class represents a function call string in a 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.

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

string

The name of the function to be constructed when generating the SQL string
$_returnType protected

string

The type name this expression will return when executed
$_typeMap protected

Cake\Database\TypeMap

Method Summary

__call() public

Helps calling the and() and or() methods transparently.
__clone() public

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

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.
_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
_castToExpression() protected

Conditionally converts the passed value to an ExpressionInterface object if the type class implements the ExpressionTypeInterface. Otherwise, returns the value unmodified.
_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.
_requiresToExpressionCasting() protected

Returns an array with the types that require values to be casted to expressions, out of the list of type names passed as parameter.
add() public

Adds one or more arguments for the function call.
addCase() public

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

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".
count() public

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.
defaultTypes() public deprecated

Allows setting default types when chaining query
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.
getName() public

Gets the name of the SQL function to be invoke in this expression.
getReturnType() public

Gets the type of the value this object will generate.
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

Check whether or not 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".
name() public deprecated

Sets the name of the SQL function to be invoke in this expression, if no value is passed it will return current name
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)".
notLike() public

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

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

Sets the type of the value this object will generate. If called without arguments, returns the current known type
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.
setName() public

Sets the name of the SQL function to be invoke in this expression.
setReturnType() public

Sets the type of the value this object will generate.
setTypeMap() public

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

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.
tieWith() public deprecated

Changes the conjunction for the conditions at this level of the expression tree. If called with no arguments it will return the currently configured value.
traverse() public

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.
type() public deprecated

Backwards compatible wrapper for tieWith()
typeMap() public deprecated

Creates a new TypeMap if $typeMap is an array, otherwise returns the existing type map or exchanges it for the given one.

Method Detail

__call() ¶ public

__call(string $method, array $args): Cake\Database\Expression\QueryExpression

Helps calling the and() and or() methods transparently.

Parameters

string $method: The method name.
array $args: The arguments to pass to the method.

Returns

Cake\Database\Expression\QueryExpression

Throws

BadMethodCallException

__clone() ¶ public

__clone(): void

Clone this object and its subtree of expressions.

Returns

void

__construct() ¶ public

__construct(string $name, array $params = [], array $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.

Examples:

$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')

Parameters

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 $types optional: associative array of types to be associated with the passed arguments
string $returnType optional: The return type of this expression

_addConditions() ¶ protected

_addConditions(array $conditions, array $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 $types: list of types associated on fields referenced in $conditions

Returns

void

_calculateType() ¶ protected

_calculateType(stringCake\Database\Expression\IdentifierExpression $field): string|null

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

Parameters

stringCake\Database\Expression\IdentifierExpression $field: The field name to get a type for.

Returns

string|null

_castToExpression() ¶ protected

_castToExpression(mixed $value, string $type): mixed

Conditionally converts the passed value to an ExpressionInterface object if the type class implements the ExpressionTypeInterface. Otherwise, returns the value unmodified.

Parameters

mixed $value: The value to converto to ExpressionInterface
string $type: The type name

Returns

mixed

_parseCondition() ¶ protected

_parseCondition(string $field, mixed $value): stringCake\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 with the actual field and operator will be extracted.
mixed $value: The value to be bound to a placeholder for the field

Returns

stringCake\Database\ExpressionInterface

_requiresToExpressionCasting() ¶ protected

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

Parameters

array $types: List of type names

Returns

array

add() ¶ public

add(array $params, array $types = [], bool $prepend = false): $this

Adds one or more arguments for the function call.

Parameters

array $params: list of arguments to be passed to the function If associative the key would be used as argument when value is 'literal'
array $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

Returns

$this

addCase() ¶ public

addCase(arrayCake\Database\ExpressionInterface $conditions, arrayCake\Database\ExpressionInterface $values = [], array $types = []): $this

Adds a new case expression to the expression object

Parameters

arrayCake\Database\ExpressionInterface $conditions: The conditions to test. Must be a ExpressionInterface instance, or an array of ExpressionInterface instances.
arrayCake\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

Returns

$this

and() ¶ public @method

and(callable|string|arrayCake\Database\ExpressionInterface $conditions): $this

Parameters

callable|string|arrayCake\Database\ExpressionInterface $conditions

Returns

$this

and_() ¶ public

and_(callable|string|arrayCake\Database\ExpressionInterface $conditions, array $types = []): Cake\Database\Expression\QueryExpression

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

Parameters

callable|string|arrayCake\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.

Returns

Cake\Database\Expression\QueryExpression

between() ¶ public

between(stringCake\Database\ExpressionInterface $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

stringCake\Database\ExpressionInterface $field: The field name to compare for values in between 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

count() ¶ public

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.

Returns

int

defaultTypes() ¶ public

defaultTypes(array|null $types = null): $this|array

Allows setting default types when chaining query

Parameters

array|null $types optional: The array of types to set.

Returns

$this|array

eq() ¶ public

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

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

Parameters

stringCake\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.

Returns

$this

equalFields() ¶ public

equalFields(string $left, string $right): $this

Builds equal condition or assignment with identifier wrapping.

Parameters

string $left: Left join condition field name.
string $right: Right join condition field name.

Returns

$this

exists() ¶ public

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

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

Parameters

Cake\Database\ExpressionInterface $query: 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

Gets default types of current type map.

Returns

array

getName() ¶ public

getName(): string

Gets the name of the SQL function to be invoke in this expression.

Returns

string

getReturnType() ¶ public

getReturnType(): string

Gets the type of the value this object will generate.

Returns

string

getTypeMap() ¶ public

getTypeMap(): Cake\Database\TypeMap

Returns the existing type map.

Returns

Cake\Database\TypeMap

gt() ¶ public

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

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

Parameters

stringCake\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.

Returns

$this

gte() ¶ public

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

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

Parameters

stringCake\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.

Returns

$this

hasNestedExpression() ¶ public

hasNestedExpression(): bool

Returns true if this expression contains any other nested ExpressionInterface objects

Returns

bool

in() ¶ public

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

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

Parameters

stringCake\Database\ExpressionInterface $field: Database field to be compared against value
string|array $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(callable $c): bool

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.

Parameters

callable $c: The callable to check.

Returns

bool

isNotNull() ¶ public

isNotNull(stringCake\Database\ExpressionInterface $field): $this

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

Parameters

stringCake\Database\ExpressionInterface $field: database field to be tested for not null

Returns

$this

isNull() ¶ public

isNull(stringCake\Database\ExpressionInterface $field): $this

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

Parameters

stringCake\Database\ExpressionInterface $field: database field to be tested for null

Returns

$this

iterateParts() ¶ public

iterateParts(callable $callable): $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 $callable: The callable to apply to each part.

Returns

$this

like() ¶ public

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

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

Parameters

stringCake\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.

Returns

$this

lt() ¶ public

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

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

Parameters

stringCake\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.

Returns

$this

lte() ¶ public

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

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

Parameters

stringCake\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.

Returns

$this

name() ¶ public

name(string|null $name = null): string|$this

Sets the name of the SQL function to be invoke in this expression, if no value is passed it will return current name

Parameters

string|null $name optional: The name of the function

Returns

string|$this

not() ¶ public

not(string|arrayCake\Database\ExpressionInterface $conditions, array $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

string|arrayCake\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.

Returns

$this

notEq() ¶ public

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

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

Parameters

stringCake\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.

Returns

$this

notExists() ¶ public

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

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

Parameters

Cake\Database\ExpressionInterface $query: the inner query

Returns

$this

notIn() ¶ public

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

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

Parameters

stringCake\Database\ExpressionInterface $field: Database field to be compared against value
array $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(stringCake\Database\ExpressionInterface $field, mixed $value, string|null $type = null): $this

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

Parameters

stringCake\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.

Returns

$this

or() ¶ public @method

or(callable|string|arrayCake\Database\ExpressionInterface $conditions): $this

Parameters

callable|string|arrayCake\Database\ExpressionInterface $conditions

Returns

$this

or_() ¶ public

or_(callable|string|arrayCake\Database\ExpressionInterface $conditions, array $types = []): Cake\Database\Expression\QueryExpression

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

Parameters

callable|string|arrayCake\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.

Returns

Cake\Database\Expression\QueryExpression

returnType() ¶ public

returnType(string|null $type = null): string|$this

Sets the type of the value this object will generate. If called without arguments, returns the current known type

Parameters

string|null $type optional: The name of the type that is to be returned

Returns

string|$this

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 $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 $types: The array of types to set.

Returns

$this

setName() ¶ public

setName(string $name): $this

Sets the name of the SQL function to be invoke in this expression.

Parameters

string $name: The name of the function

Returns

$this

setReturnType() ¶ public

setReturnType(mixed $type): $this

Sets the type of the value this object will generate.

Parameters

$type: The name of the type that is to be returned

Returns

$this

setTypeMap() ¶ public

setTypeMap(arrayCake\Database\TypeMap $typeMap): $this

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

Parameters

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

Returns

$this

sql() ¶ public

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

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.

Parameters

Cake\Database\ValueBinder $generator: Placeholder generator object

Returns

string

tieWith() ¶ public

tieWith(string|null $conjunction = null): string|$this

Changes the conjunction for the conditions at this level of the expression tree. If called with no arguments it will return the currently configured value.

Parameters

string|null $conjunction optional: value to be used for joining conditions. If null it will not set any value, but return the currently stored one

Returns

string|$this

traverse() ¶ public

traverse(callable $callable): void

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

Parameters

callable $callable: The callable to apply to all sub-expressions.

Returns

void

type() ¶ public

type(string|null $conjunction = null): string|$this

Backwards compatible wrapper for tieWith()

Parameters

string|null $conjunction optional: value to be used for joining conditions. If null it will not set any value, but return the currently stored one

Returns

string|$this

typeMap() ¶ public

typeMap(arrayCake\Database\TypeMap|null $typeMap = null): $thisCake\Database\TypeMap

Creates a new TypeMap if $typeMap is an array, otherwise returns the existing type map or exchanges it for the given one.

Parameters

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

Returns

$thisCake\Database\TypeMap

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

`$_name` ¶ protected

The name of the function to be constructed when generating the SQL string

Type

string

`$_returnType` ¶ protected

The type name this expression will return when executed

Type

string

`$_typeMap` ¶ protected

Type

Cake\Database\TypeMap

Namespaces

Class FunctionExpression

Property Summary

Method Summary

__call() public

__clone() public

__construct() public

_addConditions() protected

_calculateType() protected

_castToExpression() protected

_parseCondition() protected

_requiresToExpressionCasting() protected

add() public

addCase() public

and() public @method

and_() public

between() public

count() public

defaultTypes() public deprecated

eq() public

equalFields() public

exists() public

getConjunction() public

getDefaultTypes() public

getName() public

getReturnType() public

getTypeMap() public

gt() public

gte() public

hasNestedExpression() public

in() public

isCallable() public

isNotNull() public

isNull() public

iterateParts() public

like() public

lt() public

lte() public

name() public deprecated

not() public

notEq() public

notExists() public

notIn() public

notLike() public

or() public @method

or_() public

returnType() public deprecated

setConjunction() public

setDefaultTypes() public

setName() public

setReturnType() public

setTypeMap() public

sql() public

tieWith() public deprecated

traverse() public

type() public deprecated

typeMap() public deprecated

Method Detail

__call() ¶ public

Parameters

Returns

Throws

__clone() ¶ public

Returns

__construct() ¶ public

Examples:

Parameters

_addConditions() ¶ protected

Parameters

Returns

_calculateType() ¶ protected

Parameters

Returns

_castToExpression() ¶ protected

Parameters

Returns

_parseCondition() ¶ protected

Parameters

Returns

_requiresToExpressionCasting() ¶ protected