4 +--------------------------------------------------------------------+
5 | Copyright CiviCRM LLC. All rights reserved. |
7 | This work is published under the GNU AGPLv3 license with some |
8 | permitted exceptions and without any warranty. For full license |
9 | and copyright information, see https://civicrm.org/licensing |
10 +--------------------------------------------------------------------+
16 * @copyright CiviCRM LLC https://civicrm.org/licensing
20 namespace Civi\Api4\Generic
;
22 use Civi\Api4\Utils\CoreUtil
;
25 * Base class for all actions that need to fetch records (`Get`, `Update`, `Delete`, etc.).
27 * @package Civi\Api4\Generic
29 * @method $this setWhere(array $wheres)
30 * @method array getWhere()
31 * @method $this setOrderBy(array $order)
32 * @method array getOrderBy()
33 * @method $this setLimit(int $limit)
34 * @method int getLimit()
35 * @method $this setOffset(int $offset)
36 * @method int getOffset()
38 abstract class AbstractQueryAction
extends AbstractAction
{
41 * Criteria for selecting $ENTITIES.
44 * $example->addWhere('contact_type', 'IN', ['Individual', 'Household'])
48 protected $where = [];
51 * Array of field(s) to use in ordering the results.
56 * $example->addOrderBy('sort_name', 'ASC')
60 protected $orderBy = [];
63 * Maximum number of $ENTITIES to return.
65 * Defaults to `0` - unlimited.
67 * Note: the Api Explorer sets this to `25` by default to avoid timeouts.
68 * Change or remove this default for your application code.
75 * Zero-based index of first $ENTITY to return.
77 * Defaults to `0` - first $ENTITY found.
81 protected $offset = 0;
84 * @param string $fieldName
88 * @throws \API_Exception
90 public function addWhere(string $fieldName, string $op, $value = NULL) {
91 if (!in_array($op, CoreUtil
::getOperators())) {
92 throw new \
API_Exception('Unsupported operator');
94 $this->where
[] = [$fieldName, $op, $value];
99 * Adds one or more AND/OR/NOT clause groups
101 * @param string $operator
102 * @param mixed $condition1 ... $conditionN
103 * Either a nested array of arguments, or a variable number of arguments passed to this function.
106 * @throws \API_Exception
108 public function addClause(string $operator, $condition1) {
109 if (!is_array($condition1[0])) {
110 $condition1 = array_slice(func_get_args(), 1);
112 $this->where
[] = [$operator, $condition1];
117 * Adds to the orderBy clause
118 * @param string $fieldName
119 * @param string $direction
122 public function addOrderBy(string $fieldName, $direction = 'ASC') {
123 $this->orderBy
[$fieldName] = $direction;
128 * Produces a human-readable where clause, for the reading enjoyment of you humans.
130 * @param array $whereClause
134 protected function whereClauseToString($whereClause = NULL, $op = 'AND') {
135 if ($whereClause === NULL) {
136 $whereClause = $this->where
;
139 if (!is_array($whereClause) ||
!$whereClause) {
142 if (in_array($whereClause[0], ['AND', 'OR', 'NOT'])) {
143 $op = array_shift($whereClause);
148 return $output . '(' . $this->whereClauseToString($whereClause, $op) . ')';
150 elseif (isset($whereClause[1]) && in_array($whereClause[1], CoreUtil
::getOperators())) {
151 $output = $whereClause[0] . ' ' . $whereClause[1] . ' ';
152 if (isset($whereClause[2])) {
153 $output .= is_array($whereClause[2]) ?
'[' . implode(', ', $whereClause[2]) . ']' : $whereClause[2];
158 foreach (array_filter($whereClause) as $clause) {
159 $clauses[] = $this->whereClauseToString($clause, $op);
161 $output = implode(" $op ", $clauses);