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 $field
86 * @throws \API_Exception
88 public function addWhere($field, $op, $value = NULL) {
89 if (!in_array($op, \CRM_Core_DAO
::acceptedSQLOperators())) {
90 throw new \
API_Exception('Unsupported operator');
92 $this->where
[] = [$field, $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($operator, $condition1) {
107 if (!is_array($condition1[0])) {
108 $condition1 = array_slice(func_get_args(), 1);
110 $this->where
[] = [$operator, $condition1];
115 * @param string $field
116 * @param string $direction
119 public function addOrderBy($field, $direction = 'ASC') {
120 $this->orderBy
[$field] = $direction;
125 * A human-readable where clause, for the reading enjoyment of you humans.
127 * @param array $whereClause
131 protected function whereClauseToString($whereClause = NULL, $op = 'AND') {
132 if ($whereClause === NULL) {
133 $whereClause = $this->where
;
136 if (!is_array($whereClause) ||
!$whereClause) {
139 if (in_array($whereClause[0], ['AND', 'OR', 'NOT'])) {
140 $op = array_shift($whereClause);
145 return $output . '(' . $this->whereClauseToString($whereClause, $op) . ')';
147 elseif (isset($whereClause[1]) && in_array($whereClause[1], \CRM_Core_DAO
::acceptedSQLOperators())) {
148 $output = $whereClause[0] . ' ' . $whereClause[1] . ' ';
149 if (isset($whereClause[2])) {
150 $output .= is_array($whereClause[2]) ?
'[' . implode(', ', $whereClause[2]) . ']' : $whereClause[2];
155 foreach (array_filter($whereClause) as $clause) {
156 $clauses[] = $this->whereClauseToString($clause, $op);
158 $output = implode(" $op ", $clauses);