3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
6 | This work is published under the GNU AGPLv3 license with some |
7 | permitted exceptions and without any warranty. For full license |
8 | and copyright information, see https://civicrm.org/licensing |
9 +--------------------------------------------------------------------+
12 namespace Civi\Api4\Query
;
15 * Base class for all Sql functions.
17 * @package Civi\Api4\Query
19 abstract class SqlFunction
extends SqlExpression
{
21 protected static $params = [];
26 * Used for categorizing functions in the UI
30 protected static $category;
32 const CATEGORY_AGGREGATE
= 'aggregate',
33 CATEGORY_COMPARISON
= 'comparison',
34 CATEGORY_DATE
= 'date',
35 CATEGORY_MATH
= 'math',
36 CATEGORY_STRING
= 'string';
39 * Parse the argument string into an array of function arguments
41 protected function initialize() {
42 $arg = trim(substr($this->expr
, strpos($this->expr
, '(') +
1, -1));
43 foreach ($this->getParams() as $param) {
44 $prefix = $this->captureKeyword($param['prefix'], $arg);
45 if ($param['expr'] && isset($prefix) ||
in_array('', $param['prefix']) ||
!$param['optional']) {
46 $this->captureExpressions($arg, $param['expr'], $param['must_be'], $param['cant_be']);
47 $this->captureKeyword($param['suffix'], $arg);
53 * Shift a keyword off the beginning of the argument string and into the argument array.
55 * @param array $keywords
56 * Whitelist of keywords
60 private function captureKeyword($keywords, &$arg) {
61 foreach (array_filter($keywords) as $key) {
62 if (strpos($arg, $key . ' ') === 0) {
64 $arg = ltrim(substr($arg, strlen($key)));
72 * Shifts 0 or more expressions off the argument string and into the argument array
76 * @param array $mustBe
77 * @param array $cantBe
78 * @throws \API_Exception
80 private function captureExpressions(&$arg, $limit, $mustBe, $cantBe) {
84 $item = $this->captureExpression($arg);
85 $arg = ltrim(substr($arg, strlen($item)));
86 $expr = SqlExpression
::convert($item, FALSE, $mustBe, $cantBe);
87 $this->fields
= array_merge($this->fields
, $expr->getFields());
91 $this->args
[] = $expr;
93 // Keep going if we have a comma indicating another expression follows
94 if ($captured < $limit && substr($arg, 0, 1) === ',') {
95 $arg = ltrim(substr($arg, 1));
104 * Scans the beginning of a string for an expression; stops when it hits delimiter
109 private function captureExpression($arg) {
110 $chars = str_split($arg);
111 $isEscaped = $quote = NULL;
113 $quotes = ['"', "'"];
117 $enclosures = array_fill_keys($brackets, 0);
118 foreach ($chars as $index => $char) {
119 if (!$isEscaped && in_array($char, $quotes, TRUE)) {
120 // Open quotes - we'll ignore everything inside
125 elseif ($char === $quote) {
130 // Delineates end of expression
131 if (($char == ',' ||
$char == ' ') && !array_filter($enclosures)) {
134 // Open brackets - we'll ignore delineators inside
135 if (isset($enclosures[$char])) {
136 $enclosures[$char]++
;
139 if (isset($brackets[$char]) && $enclosures[$brackets[$char]]) {
140 $enclosures[$brackets[$char]]--;
144 // We are escaping the next char if this is a backslash not preceded by an odd number of backslashes
145 $isEscaped = $char === '\\' && ((strlen($item) - strlen(rtrim($item, '\\'))) %
2);
150 public function render(array $fieldList): string {
151 $output = $this->getName() . '(';
152 foreach ($this->args
as $index => $arg) {
153 if ($index && $arg !== ',') {
156 if (is_object($arg)) {
157 $output .= $arg->render($fieldList);
163 return $output . ')';
169 public function getAlias(): string {
170 return $this->alias ??
$this->getName() . ':' . implode('_', $this->fields
);
174 * Get the name of this sql function.
177 public static function getName(): string {
178 $className = static::class;
179 return substr($className, strrpos($className, 'SqlFunction') +
11);
183 * Get the param metadata for this sql function.
186 public static function getParams(): array {
188 foreach (static::$params as $param) {
189 // Merge in defaults to ensure each param has these properties
190 $params[] = $param +
[
196 'cant_be' => ['SqlWild'],
205 public static function getCategory(): string {
206 return static::$category;
212 abstract public static function getTitle(): string;