1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
11: * @link https://cakephp.org CakePHP(tm) Project
12: * @since 3.0.0
13: * @license https://opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\Database\Expression;
16:
17: use Cake\Database\ExpressionInterface;
18: use Cake\Database\Query;
19: use Cake\Database\TypedResultInterface;
20: use Cake\Database\TypedResultTrait;
21: use Cake\Database\Type\ExpressionTypeCasterTrait;
22: use Cake\Database\ValueBinder;
23:
24: /**
25: * This class represents a function call string in a SQL statement. Calls can be
26: * constructed by passing the name of the function and a list of params.
27: * For security reasons, all params passed are quoted by default unless
28: * explicitly told otherwise.
29: */
30: class FunctionExpression extends QueryExpression implements TypedResultInterface
31: {
32: use ExpressionTypeCasterTrait;
33: use TypedResultTrait;
34:
35: /**
36: * The name of the function to be constructed when generating the SQL string
37: *
38: * @var string
39: */
40: protected $_name;
41:
42: /**
43: * Constructor. Takes a name for the function to be invoked and a list of params
44: * to be passed into the function. Optionally you can pass a list of types to
45: * be used for each bound param.
46: *
47: * By default, all params that are passed will be quoted. If you wish to use
48: * literal arguments, you need to explicitly hint this function.
49: *
50: * ### Examples:
51: *
52: * `$f = new FunctionExpression('CONCAT', ['CakePHP', ' rules']);`
53: *
54: * Previous line will generate `CONCAT('CakePHP', ' rules')`
55: *
56: * `$f = new FunctionExpression('CONCAT', ['name' => 'literal', ' rules']);`
57: *
58: * Will produce `CONCAT(name, ' rules')`
59: *
60: * @param string $name the name of the function to be constructed
61: * @param array $params list of arguments to be passed to the function
62: * If associative the key would be used as argument when value is 'literal'
63: * @param array $types associative array of types to be associated with the
64: * passed arguments
65: * @param string $returnType The return type of this expression
66: */
67: public function __construct($name, $params = [], $types = [], $returnType = 'string')
68: {
69: $this->_name = $name;
70: $this->_returnType = $returnType;
71: parent::__construct($params, $types, ',');
72: }
73:
74: /**
75: * Sets the name of the SQL function to be invoke in this expression.
76: *
77: * @param string $name The name of the function
78: * @return $this
79: */
80: public function setName($name)
81: {
82: $this->_name = $name;
83:
84: return $this;
85: }
86:
87: /**
88: * Gets the name of the SQL function to be invoke in this expression.
89: *
90: * @return string
91: */
92: public function getName()
93: {
94: return $this->_name;
95: }
96:
97: /**
98: * Sets the name of the SQL function to be invoke in this expression,
99: * if no value is passed it will return current name
100: *
101: * @deprecated 3.4.0 Use setName()/getName() instead.
102: * @param string|null $name The name of the function
103: * @return string|$this
104: */
105: public function name($name = null)
106: {
107: deprecationWarning(
108: 'FunctionExpression::name() is deprecated. ' .
109: 'Use FunctionExpression::setName()/getName() instead.'
110: );
111: if ($name !== null) {
112: return $this->setName($name);
113: }
114:
115: return $this->getName();
116: }
117:
118: /**
119: * Adds one or more arguments for the function call.
120: *
121: * @param array $params list of arguments to be passed to the function
122: * If associative the key would be used as argument when value is 'literal'
123: * @param array $types associative array of types to be associated with the
124: * passed arguments
125: * @param bool $prepend Whether to prepend or append to the list of arguments
126: * @see \Cake\Database\Expression\FunctionExpression::__construct() for more details.
127: * @return $this
128: */
129: public function add($params, $types = [], $prepend = false)
130: {
131: $put = $prepend ? 'array_unshift' : 'array_push';
132: $typeMap = $this->getTypeMap()->setTypes($types);
133: foreach ($params as $k => $p) {
134: if ($p === 'literal') {
135: $put($this->_conditions, $k);
136: continue;
137: }
138:
139: if ($p === 'identifier') {
140: $put($this->_conditions, new IdentifierExpression($k));
141: continue;
142: }
143:
144: $type = $typeMap->type($k);
145:
146: if ($type !== null && !$p instanceof ExpressionInterface) {
147: $p = $this->_castToExpression($p, $type);
148: }
149:
150: if ($p instanceof ExpressionInterface) {
151: $put($this->_conditions, $p);
152: continue;
153: }
154:
155: $put($this->_conditions, ['value' => $p, 'type' => $type]);
156: }
157:
158: return $this;
159: }
160:
161: /**
162: * Returns the string representation of this object so that it can be used in a
163: * SQL query. Note that values condition values are not included in the string,
164: * in their place placeholders are put and can be replaced by the quoted values
165: * accordingly.
166: *
167: * @param \Cake\Database\ValueBinder $generator Placeholder generator object
168: * @return string
169: */
170: public function sql(ValueBinder $generator)
171: {
172: $parts = [];
173: foreach ($this->_conditions as $condition) {
174: if ($condition instanceof Query) {
175: $condition = sprintf('(%s)', $condition->sql($generator));
176: } elseif ($condition instanceof ExpressionInterface) {
177: $condition = $condition->sql($generator);
178: } elseif (is_array($condition)) {
179: $p = $generator->placeholder('param');
180: $generator->bind($p, $condition['value'], $condition['type']);
181: $condition = $p;
182: }
183: $parts[] = $condition;
184: }
185:
186: return $this->_name . sprintf('(%s)', implode(
187: $this->_conjunction . ' ',
188: $parts
189: ));
190: }
191:
192: /**
193: * The name of the function is in itself an expression to generate, thus
194: * always adding 1 to the amount of expressions stored in this object.
195: *
196: * @return int
197: */
198: public function count()
199: {
200: return 1 + count($this->_conditions);
201: }
202: }
203: