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 +--------------------------------------------------------------------+
13 namespace Civi\Api4\Generic
;
15 use Civi\Api4\Utils\CoreUtil
;
18 * Base class for all actions that need to fetch records (`Get`, `Update`, `Delete`, etc.).
20 * @package Civi\Api4\Generic
22 * @method $this setWhere(array $wheres)
23 * @method array getWhere()
24 * @method $this setOrderBy(array $order)
25 * @method array getOrderBy()
26 * @method $this setLimit(int $limit)
27 * @method int getLimit()
28 * @method $this setOffset(int $offset)
29 * @method int getOffset()
31 abstract class AbstractQueryAction
extends AbstractAction
{
34 * Criteria for selecting $ENTITIES.
37 * $example->addWhere('contact_type', 'IN', ['Individual', 'Household'])
41 protected $where = [];
44 * Array of field(s) to use in ordering the results.
49 * $example->addOrderBy('sort_name', 'ASC')
53 protected $orderBy = [];
56 * Maximum number of $ENTITIES to return.
58 * Defaults to `0` - unlimited.
60 * Note: the Api Explorer sets this to `25` by default to avoid timeouts.
61 * Change or remove this default for your application code.
68 * Zero-based index of first $ENTITY to return.
70 * Defaults to `0` - first $ENTITY found.
74 protected $offset = 0;
77 * @param string $fieldName
81 * @throws \API_Exception
83 public function addWhere(string $fieldName, string $op, $value = NULL) {
84 if (!in_array($op, CoreUtil
::getOperators())) {
85 throw new \
API_Exception('Unsupported operator');
87 $this->where
[] = [$fieldName, $op, $value];
92 * Adds one or more AND/OR/NOT clause groups
94 * @param string $operator
95 * @param mixed $condition1 ... $conditionN
96 * Either a nested array of arguments, or a variable number of arguments passed to this function.
99 * @throws \API_Exception
101 public function addClause(string $operator, $condition1) {
102 if (!is_array($condition1[0])) {
103 $condition1 = array_slice(func_get_args(), 1);
105 $this->where
[] = [$operator, $condition1];
110 * Adds to the orderBy clause
111 * @param string $fieldName
112 * @param string $direction
115 public function addOrderBy(string $fieldName, $direction = 'ASC') {
116 $this->orderBy
[$fieldName] = $direction;
121 * Produces a human-readable where clause, for the reading enjoyment of you humans.
123 * @param array $whereClause
127 protected function whereClauseToString($whereClause = NULL, $op = 'AND') {
128 if ($whereClause === NULL) {
129 $whereClause = $this->where
;
132 if (!is_array($whereClause) ||
!$whereClause) {
135 if (in_array($whereClause[0], ['AND', 'OR', 'NOT'])) {
136 $op = array_shift($whereClause);
141 return $output . '(' . $this->whereClauseToString($whereClause, $op) . ')';
143 elseif (isset($whereClause[1]) && in_array($whereClause[1], CoreUtil
::getOperators())) {
144 $output = $whereClause[0] . ' ' . $whereClause[1] . ' ';
145 if (isset($whereClause[2])) {
146 $output .= is_array($whereClause[2]) ?
'[' . implode(', ', $whereClause[2]) . ']' : $whereClause[2];
151 foreach (array_filter($whereClause) as $clause) {
152 $clauses[] = $this->whereClauseToString($clause, $op);
154 $output = implode(" $op ", $clauses);