W3cubDocs

/CakePHP 3.8

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
Extended by Cake\Database\Expression\FunctionExpression implements Cake\Database\TypedResultInterface uses Cake\Database\Type\ExpressionTypeCasterTrait , Cake\Database\TypedResultTrait

Properties summary

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

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() public
    Adds 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() public
    Gets the name of the SQL function to be invoke in this expression.
  • 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

  • setName() public
    Sets 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

integer

Overrides

Cake\Database\Expression\QueryExpression::count()

getName()source public

getName( )

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

Returns

string

name()source public deprecated

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

string

Overrides

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

__clone()source public

__clone( )

Clone this object and its subtree of expressions.

_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|null
The 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_( callable|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

callable|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

string

gt()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

boolean

in()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

boolean
Valid 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_( callable|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

callable|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 deprecated

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 ExpressionInterface

Parameters

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

Implementation of

Cake\Database\ExpressionInterface::traverse()

type()source public deprecated

type( string|null $conjunction = null )

Backwards compatible wrapper for tieWith()

Deprecated

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

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

array

Methods used from Cake\Database\TypedResultTrait

getReturnType()source public

getReturnType( )

Gets the type of the value this object will generate.

Returns

string

returnType()source public deprecated

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 deprecated

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

array

getTypeMap()source public

getTypeMap( )

Returns the existing type map.

Returns

Cake\Database\TypeMap

setDefaultTypes()source public

setDefaultTypes( array $types )

Overwrite the default type mappings for fields in the implementing object.

This method is useful if you need to set type mappings that are shared across multiple functions/expressions in a query.

To add a default without overwriting existing ones use getTypeMap()->addDefaults()

Parameters

array $types
The array of types to set.

Returns


$this

See

\Cake\Database\TypeMap::setDefaults()

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 deprecated

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–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/3.8/class-Cake.Database.Expression.FunctionExpression.html