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
22 namespace Civi\Api4\Generic
;
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 items.
43 * $example->addWhere('contact_type', 'IN', array('Individual', 'Household'))
47 protected $where = [];
50 * Array of field(s) to use in ordering the results
54 * $example->addOrderBy('sort_name', 'ASC')
58 protected $orderBy = [];
61 * Maximum number of results to return.
63 * Defaults to unlimited.
65 * Note: the Api Explorer sets this to 25 by default to avoid timeouts.
66 * Change or remove this default for your application code.
73 * Zero-based index of first result to return.
75 * Defaults to "0" - first record.
79 protected $offset = 0;
82 * @param string $fieldName
86 * @throws \API_Exception
88 public function addWhere(string $fieldName, string $op, $value = NULL) {
89 if (!in_array($op, \CRM_Core_DAO
::acceptedSQLOperators())) {
90 throw new \
API_Exception('Unsupported operator');
92 $this->where
[] = [$fieldName, $op, $value];
97 * Adds one or more AND/OR/NOT clause groups
99 * @param string $operator
100 * @param mixed $condition1 ... $conditionN
101 * Either a nested array of arguments, or a variable number of arguments passed to this function.
104 * @throws \API_Exception
106 public function addClause(string $operator, $condition1) {
107 if (!is_array($condition1[0])) {
108 $condition1 = array_slice(func_get_args(), 1);
110 $this->where
[] = [$operator, $condition1];
115 * Adds to the orderBy clause
116 * @param string $fieldName
117 * @param string $direction
120 public function addOrderBy(string $fieldName, $direction = 'ASC') {
121 $this->orderBy
[$fieldName] = $direction;
126 * Produces a human-readable where clause, for the reading enjoyment of you humans.
128 * @param array $whereClause
132 protected function whereClauseToString($whereClause = NULL, $op = 'AND') {
133 if ($whereClause === NULL) {
134 $whereClause = $this->where
;
137 if (!is_array($whereClause) ||
!$whereClause) {
140 if (in_array($whereClause[0], ['AND', 'OR', 'NOT'])) {
141 $op = array_shift($whereClause);
146 return $output . '(' . $this->whereClauseToString($whereClause, $op) . ')';
148 elseif (isset($whereClause[1]) && in_array($whereClause[1], \CRM_Core_DAO
::acceptedSQLOperators())) {
149 $output = $whereClause[0] . ' ' . $whereClause[1] . ' ';
150 if (isset($whereClause[2])) {
151 $output .= is_array($whereClause[2]) ?
'[' . implode(', ', $whereClause[2]) . ']' : $whereClause[2];
156 foreach (array_filter($whereClause) as $clause) {
157 $clauses[] = $this->whereClauseToString($clause, $op);
159 $output = implode(" $op ", $clauses);