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.
- Cake\Database\Expression\QueryExpression implements Cake\Database\ExpressionInterface, Countable uses Cake\Database\TypeMapTrait
-
Cake\Database\Expression\FunctionExpression implements Cake\Database\TypedResultInterface uses Cake\Database\Type\ExpressionTypeCasterTrait , Cake\Database\TypedResultTrait
Properties summary
-
$_name
protectedThe name of the function to be constructed when generating the SQL stringstring
Inherited Properties
Method Summary
- __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.
- add() publicAdds one or more arguments for the function call.
- 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.
- getName() publicGets the name of the SQL function to be invoke in this expression.
- name() public
Sets the name of the SQL function to be invoke in this expression, if no value is passed it will return current name
- setName() publicSets the name of the SQL function to be invoke in this expression.
- 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.
Method Detail
__construct()source 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 'string' - The return type of this expression
Overrides
Cake\Database\Expression\QueryExpression::__construct()
add()source public
add( array $params , array $types [] , boolean $prepend false )
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
- boolean
$prepend
optional false - Whether to prepend or append to the list of arguments
Returns
$this
See
\Cake\Database\Expression\FunctionExpression::__construct() for more details.Overrides
Cake\Database\Expression\QueryExpression::add()
count()source public
count( )
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
integerOverrides
Cake\Database\Expression\QueryExpression::count()
getName()source public
getName( )
Gets the name of the SQL function to be invoke in this expression.
Returns
stringname()source public
name( string|null $name null )
Sets the name of the SQL function to be invoke in this expression, if no value is passed it will return current name
Deprecated
3.4.0 Use setName()/getName() instead.Parameters
- string|null
$name
optional null - The name of the function
Returns
string|Cake\Database\Expression\FunctionExpression
$this
setName()source public
setName( string $name )
Sets the name of the SQL function to be invoke in this expression.
Parameters
- string
$name
- The name of the function
Returns
$this
sql()source public
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.
Parameters
- Cake\Database\ValueBinder
$generator
- Placeholder generator object
Returns
stringOverrides
Cake\Database\Expression\QueryExpression::sql()
Methods inherited from Cake\Database\Expression\QueryExpression
__call()source public
__call( string $method , array $args )
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_addConditions()source protected
_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.
Parameters
- array
$conditions
- list of conditions to be stored in this object
- array
$types
- list of types associated on fields referenced in $conditions
_calculateType()source protected
_calculateType( string|Cake\Database\Expression\IdentifierExpression $field )
Returns the type name for the passed field if it was stored in the typeMap
Parameters
- string|
Cake\Database\Expression\IdentifierExpression
$field
- The field name to get a type for.
Returns
string|nullThe computed type or null, if the type is unknown.
_parseCondition()source protected
_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.
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
string|Cake\Database\ExpressionInterface
addCase()source public
addCase( array|Cake\Database\ExpressionInterface $conditions , array|Cake\Database\ExpressionInterface $values [] , array $types [] )
Adds a new case expression to the expression object
Parameters
- 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
Returns
$this
and_()source public
and_( string|array|Cake\Database\ExpressionInterface $conditions , array $types [] )
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "AND"
Parameters
- 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.
Returns
Cake\Database\Expression\QueryExpression
between()source public
between( string|Cake\Database\ExpressionInterface $field , mixed $from , mixed $to , string|null $type null )
Adds a new condition to the expression object in the form "field BETWEEN from AND to".
Parameters
- string|
Cake\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 null - the type name for $value as configured using the Type map.
Returns
$this
eq()source public
eq( string|Cake\Database\ExpressionInterface $field , mixed $value , string|null $type null )
Adds a new condition to the expression object in the form "field = value".
Parameters
- 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 null 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()source public
equalFields( string $left , string $right )
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()source public
exists( Cake\Database\ExpressionInterface $query )
Adds a new condition to the expression object in the form "EXISTS (...)".
Parameters
-
Cake\Database\ExpressionInterface
$query
- the inner query
Returns
$this
getConjunction()source public
getConjunction( )
Gets the currently configured conjunction for the conditions at this level of the expression tree.
Returns
stringgt()source public
gt( string|Cake\Database\ExpressionInterface $field , mixed $value , string|null $type null )
Adds a new condition to the expression object in the form "field > value".
Parameters
- 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 null - the type name for $value as configured using the Type map.
Returns
$this
gte()source public
gte( string|Cake\Database\ExpressionInterface $field , mixed $value , string|null $type null )
Adds a new condition to the expression object in the form "field >= value".
Parameters
- 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 null - the type name for $value as configured using the Type map.
Returns
$this
hasNestedExpression()source public
hasNestedExpression( )
Returns true if this expression contains any other nested ExpressionInterface objects
Returns
booleanin()source public
in( string|Cake\Database\ExpressionInterface $field , string|array $values , string|null $type null )
Adds a new condition to the expression object in the form "field IN (value1, value2)".
Parameters
- string|
Cake\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 null - the type name for $value as configured using the Type map.
Returns
$this
isCallable()source public
isCallable( callable $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.
Parameters
- callable
$c
- The callable to check.
Returns
booleanValid callable.
isNotNull()source public
isNotNull( string|Cake\Database\ExpressionInterface $field )
Adds a new condition to the expression object in the form "field IS NOT NULL".
Parameters
- string|
Cake\Database\ExpressionInterface
$field
database field to be tested for not null
Returns
$this
isNull()source public
isNull( string|Cake\Database\ExpressionInterface $field )
Adds a new condition to the expression object in the form "field IS NULL".
Parameters
- string|
Cake\Database\ExpressionInterface
$field
database field to be tested for null
Returns
$this
iterateParts()source public
iterateParts( callable $callable )
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()source public
like( string|Cake\Database\ExpressionInterface $field , mixed $value , string|null $type null )
Adds a new condition to the expression object in the form "field LIKE value".
Parameters
- 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 null - the type name for $value as configured using the Type map.
Returns
$this
lt()source public
lt( string|Cake\Database\ExpressionInterface $field , mixed $value , string|null $type null )
Adds a new condition to the expression object in the form "field < value".
Parameters
- 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 null - the type name for $value as configured using the Type map.
Returns
$this
lte()source public
lte( string|Cake\Database\ExpressionInterface $field , mixed $value , string|null $type null )
Adds a new condition to the expression object in the form "field <= value".
Parameters
- 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 null - the type name for $value as configured using the Type map.
Returns
$this
not()source public
not( string|array|Cake\Database\ExpressionInterface $conditions , array $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.
Parameters
- 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.
Returns
$this
notEq()source public
notEq( string|Cake\Database\ExpressionInterface $field , mixed $value , string|null $type null )
Adds a new condition to the expression object in the form "field != value".
Parameters
- 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 null 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()source public
notExists( Cake\Database\ExpressionInterface $query )
Adds a new condition to the expression object in the form "NOT EXISTS (...)".
Parameters
-
Cake\Database\ExpressionInterface
$query
- the inner query
Returns
$this
notIn()source public
notIn( string|Cake\Database\ExpressionInterface $field , array $values , string|null $type null )
Adds a new condition to the expression object in the form "field NOT IN (value1, value2)".
Parameters
- string|
Cake\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 null - the type name for $value as configured using the Type map.
Returns
$this
notLike()source public
notLike( string|Cake\Database\ExpressionInterface $field , mixed $value , string|null $type null )
Adds a new condition to the expression object in the form "field NOT LIKE value".
Parameters
- 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 null - the type name for $value as configured using the Type map.
Returns
$this
or_()source public
or_( string|array|Cake\Database\ExpressionInterface $conditions , array $types [] )
Returns a new QueryExpression object containing all the conditions passed and set up the conjunction to be "OR"
Parameters
- 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.
Returns
Cake\Database\Expression\QueryExpression
setConjunction()source public
setConjunction( string $conjunction )
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
tieWith()source public
tieWith( string|null $conjunction null )
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.
Deprecated
3.4.0 Use setConjunction()/getConjunction() instead.Parameters
- string|null
$conjunction
optional null value to be used for joining conditions. If null it will not set any value, but return the currently stored one
Returns
string|Cake\Database\Expression\QueryExpression
$this
traverse()source public
traverse( callable $callable )
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 a QueryExpression
Parameters
- callable
$callable
- The callable to apply to all sub-expressions.
Implementation of
Cake\Database\ExpressionInterface::traverse()
type()source public
type( string|null $conjunction null )
Backwards compatible wrapper for tieWith()
Deprecated
3.2.0 Use tieWith() insteadParameters
- string|null
$conjunction
optional null value to be used for joining conditions. If null it will not set any value, but return the currently stored one
Returns
string|Cake\Database\Expression\QueryExpression
$this
Methods used from Cake\Database\Type\ExpressionTypeCasterTrait
_castToExpression()source protected
_castToExpression( mixed $value , string $type )
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_requiresToExpressionCasting()source protected
_requiresToExpressionCasting( array $types )
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
arrayMethods used from Cake\Database\TypedResultTrait
getReturnType()source public
getReturnType( )
Gets the type of the value this object will generate.
Returns
stringreturnType()source public
returnType( string|null $type null )
Sets the type of the value this object will generate. If called without arguments, returns the current known type
Deprecated
3.5.0 Use getReturnType()/setReturnType() instead.Parameters
- string|null
$type
optional null - The name of the type that is to be returned
Returns
string|Cake\Database\TypedResultTrait
$this
setReturnType()source public
setReturnType( string $type )
Sets the type of the value this object will generate.
Parameters
- string
$type
- The name of the type that is to be returned
Returns
$this
Methods used from Cake\Database\TypeMapTrait
defaultTypes()source public
defaultTypes( array $types null )
Allows setting default types when chaining query
Deprecated
3.4.0 Use setDefaultTypes()/getDefaultTypes() instead.Parameters
- array
$types
optional null - The array of types to set.
Returns
$this|array
getDefaultTypes()source public
getDefaultTypes( )
Gets default types of current type map.
Returns
arraygetTypeMap()source public
getTypeMap( )
Returns the existing type map.
Returns
Cake\Database\TypeMap
setDefaultTypes()source public
setDefaultTypes( array $types )
Allows setting default types when chaining query.
Parameters
- array
$types
- The array of types to set.
Returns
$this
setTypeMap()source public
setTypeMap( array|Cake\Database\TypeMap $typeMap )
Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.
Parameters
- array|
Cake\Database\TypeMap
$typeMap
- Creates a TypeMap if array, otherwise sets the given TypeMap
Returns
$this
typeMap()source public
typeMap( array|Cake\Database\TypeMap|null $typeMap null )
Creates a new TypeMap if $typeMap is an array, otherwise returns the existing type map or exchanges it for the given one.
Deprecated
3.4.0 Use setTypeMap()/getTypeMap() instead.Parameters
- array|
Cake\Database\TypeMap
|null$typeMap
optional null - Creates a TypeMap if array, otherwise sets the given TypeMap
Returns
$this|\Cake\Database\TypeMap
Magic methods inherited from Cake\Database\TypedResultInterface
getReturnType() |
Properties detail
$_namesource
protected string
The name of the function to be constructed when generating the SQL string
© 2005–2017 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/3.4/class-Cake.Database.Expression.FunctionExpression.html