Commit | Line | Data |
---|---|---|
19b53e5b C |
1 | <?php |
2 | ||
380f3545 TO |
3 | /* |
4 | +--------------------------------------------------------------------+ | |
41498ac5 | 5 | | Copyright CiviCRM LLC. All rights reserved. | |
380f3545 | 6 | | | |
41498ac5 TO |
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 | | |
380f3545 TO |
10 | +--------------------------------------------------------------------+ |
11 | */ | |
12 | ||
13 | /** | |
14 | * | |
15 | * @package CRM | |
ca5cec67 | 16 | * @copyright CiviCRM LLC https://civicrm.org/licensing |
380f3545 TO |
17 | * $Id$ |
18 | * | |
19 | */ | |
20 | ||
21 | ||
19b53e5b C |
22 | namespace Civi\Api4\Generic; |
23 | ||
39e0f675 CW |
24 | use Civi\Api4\Utils\SelectUtil; |
25 | ||
19b53e5b | 26 | /** |
fc95d9a5 | 27 | * Base class for all `Get` api actions. |
19b53e5b C |
28 | * |
29 | * @package Civi\Api4\Generic | |
30 | * | |
121ec912 | 31 | * @method $this setSelect(array $selects) Set array of fields to be selected (wildcard * allowed) |
19b53e5b C |
32 | * @method array getSelect() |
33 | */ | |
34 | abstract class AbstractGetAction extends AbstractQueryAction { | |
35 | ||
36 | /** | |
fc95d9a5 | 37 | * Fields to return for each $ENTITY. Defaults to all fields `[*]`. |
39e0f675 CW |
38 | * |
39 | * Use the * wildcard by itself to select all available fields, or use it to match similarly-named fields. | |
136ca5bb | 40 | * E.g. `is_*` will match fields named is_primary, is_active, etc. |
19b53e5b | 41 | * |
e3c6d5ff | 42 | * Set to `["row_count"]` to return only the number of $ENTITIES found. |
19b53e5b C |
43 | * |
44 | * @var array | |
45 | */ | |
46 | protected $select = []; | |
47 | ||
48 | /** | |
49 | * Only return the number of found items. | |
50 | * | |
51 | * @return $this | |
52 | */ | |
53 | public function selectRowCount() { | |
54 | $this->select = ['row_count']; | |
55 | return $this; | |
56 | } | |
57 | ||
58 | /** | |
59 | * Adds field defaults to the where clause. | |
60 | * | |
61 | * Note: it will skip adding field defaults when fetching records by id, | |
62 | * or if that field has already been added to the where clause. | |
63 | * | |
64 | * @throws \API_Exception | |
65 | */ | |
66 | protected function setDefaultWhereClause() { | |
67 | if (!$this->_itemsToGet('id')) { | |
68 | $fields = $this->entityFields(); | |
69 | foreach ($fields as $field) { | |
70 | if (isset($field['default_value']) && !$this->_whereContains($field['name'])) { | |
71 | $this->addWhere($field['name'], '=', $field['default_value']); | |
72 | } | |
73 | } | |
74 | } | |
75 | } | |
76 | ||
39e0f675 CW |
77 | /** |
78 | * Adds all fields matched by the * wildcard | |
79 | * | |
80 | * @throws \API_Exception | |
81 | */ | |
82 | protected function expandSelectClauseWildcards() { | |
b0932d1e | 83 | $wildFields = array_filter($this->select, function($item) { |
3176b04c | 84 | return strpos($item, '*') !== FALSE && strpos($item, '.') === FALSE && strpos($item, '(') === FALSE && strpos($item, ' ') === FALSE; |
b0932d1e CW |
85 | }); |
86 | foreach ($wildFields as $item) { | |
87 | $pos = array_search($item, array_values($this->select)); | |
88 | $matches = SelectUtil::getMatchingFields($item, array_column($this->entityFields(), 'name')); | |
89 | array_splice($this->select, $pos, 1, $matches); | |
39e0f675 | 90 | } |
b0932d1e | 91 | $this->select = array_unique($this->select); |
39e0f675 CW |
92 | } |
93 | ||
19b53e5b C |
94 | /** |
95 | * Helper to parse the WHERE param for getRecords to perform simple pre-filtering. | |
96 | * | |
97 | * This is intended to optimize some common use-cases e.g. calling the api to get | |
98 | * one or more records by name or id. | |
99 | * | |
100 | * Ex: If getRecords fetches a long list of items each with a unique name, | |
101 | * but the user has specified a single record to retrieve, you can optimize the call | |
136ca5bb | 102 | * by checking `$this->_itemsToGet('name')` and only fetching the item(s) with that name. |
19b53e5b C |
103 | * |
104 | * @param string $field | |
105 | * @return array|null | |
106 | */ | |
107 | protected function _itemsToGet($field) { | |
108 | foreach ($this->where as $clause) { | |
109 | // Look for exact-match operators (=, IN, or LIKE with no wildcard) | |
110 | if ($clause[0] == $field && (in_array($clause[1], ['=', 'IN']) || ($clause[1] == 'LIKE' && !(is_string($clause[2]) && strpos($clause[2], '%') !== FALSE)))) { | |
111 | return (array) $clause[2]; | |
112 | } | |
113 | } | |
114 | return NULL; | |
115 | } | |
116 | ||
117 | /** | |
07d6d25b | 118 | * Helper to see if field(s) should be selected by the getRecords function. |
19b53e5b C |
119 | * |
120 | * Checks the SELECT, WHERE and ORDER BY params to see what fields are needed. | |
121 | * | |
122 | * Note that if no SELECT clause has been set then all fields should be selected | |
123 | * and this function will always return TRUE. | |
124 | * | |
07d6d25b CW |
125 | * @param string ...$fieldNames |
126 | * One or more field names to check (uses OR if multiple) | |
19b53e5b | 127 | * @return bool |
07d6d25b | 128 | * Returns true if any given fields are in use. |
19b53e5b | 129 | */ |
07d6d25b CW |
130 | protected function _isFieldSelected(string ...$fieldNames) { |
131 | if (!$this->select || array_intersect($fieldNames, array_merge($this->select, array_keys($this->orderBy)))) { | |
19b53e5b C |
132 | return TRUE; |
133 | } | |
07d6d25b | 134 | return $this->_whereContains($fieldNames); |
19b53e5b C |
135 | } |
136 | ||
137 | /** | |
07d6d25b | 138 | * Walk through the where clause and check if field(s) are in use. |
19b53e5b | 139 | * |
07d6d25b CW |
140 | * @param string|array $fieldName |
141 | * A single fieldName or an array of names (uses OR if multiple) | |
19b53e5b C |
142 | * @param array $clauses |
143 | * @return bool | |
07d6d25b | 144 | * Returns true if any given fields are found in the where clause. |
19b53e5b | 145 | */ |
07d6d25b | 146 | protected function _whereContains($fieldName, $clauses = NULL) { |
19b53e5b C |
147 | if ($clauses === NULL) { |
148 | $clauses = $this->where; | |
149 | } | |
07d6d25b | 150 | $fieldName = (array) $fieldName; |
19b53e5b C |
151 | foreach ($clauses as $clause) { |
152 | if (is_array($clause) && is_string($clause[0])) { | |
07d6d25b | 153 | if (in_array($clause[0], $fieldName)) { |
19b53e5b C |
154 | return TRUE; |
155 | } | |
156 | elseif (is_array($clause[1])) { | |
07d6d25b | 157 | return $this->_whereContains($fieldName, $clause[1]); |
19b53e5b C |
158 | } |
159 | } | |
160 | } | |
161 | return FALSE; | |
162 | } | |
163 | ||
121ec912 CW |
164 | /** |
165 | * Add one or more fields to be selected (wildcard * allowed) | |
166 | * @param string ...$fieldNames | |
167 | * @return $this | |
168 | */ | |
169 | public function addSelect(string ...$fieldNames) { | |
170 | $this->select = array_merge($this->select, $fieldNames); | |
171 | return $this; | |
172 | } | |
173 | ||
19b53e5b | 174 | } |