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\API\Exception\NotImplementedException
;
25 * Lists information about fields for the $ENTITY entity.
27 * This field information is also known as "metadata."
29 * Note that different actions may support different lists of fields.
30 * By default this will fetch the field list relevant to `get`,
31 * but a different list may be returned if you specify another action.
33 * @method $this setLoadOptions(bool|array $value)
34 * @method bool|array getLoadOptions()
35 * @method $this setAction(string $value)
36 * @method $this setValues(array $values)
37 * @method array getValues()
39 class BasicGetFieldsAction
extends BasicGetAction
{
42 * Fetch option lists for fields?
44 * This parameter can be either a boolean or an array of attributes to return from the option list:
46 * - If `FALSE`, each field's `options` property will be a boolean indicating whether the field has an option list
47 * - If `TRUE`, `options` will be returned as a flat array of the option list's `[id => label]`
48 * - If an array, `options` will be a non-associative array of requested properties:
49 * id, name, label, abbr, description, color, icon
50 * e.g. `loadOptions: ['id', 'name', 'label']` will return an array like `[[id: 1, name: 'Meeting', label: 'Meeting'], ...]`
51 * (note that names and labels are generally ONLY the same when the site's language is set to English).
55 protected $loadOptions = FALSE;
58 * Fields will be returned appropriate to the specified action (get, create, delete, etc.)
62 protected $action = 'get';
65 * Fields will be returned appropriate to the specified values (e.g. ['contact_type' => 'Individual'])
69 protected $values = [];
72 * To implement getFields for your own entity:
74 * 1. From your entity class add a static getFields method.
75 * 2. That method should construct and return this class.
76 * 3. The 3rd argument passed to this constructor should be a function that returns an
77 * array of fields for your entity's CRUD actions.
78 * 4. For non-crud actions that need a different set of fields, you can override the
79 * list from step 3 on a per-action basis by defining a fields() method in that action.
80 * See for example BasicGetFieldsAction::fields() or GetActions::fields().
82 * @param Result $result
83 * @throws \Civi\API\Exception\NotImplementedException
85 public function _run(Result
$result) {
87 $actionClass = \Civi\API\Request
::create($this->getEntityName(), $this->getAction(), ['version' => 4]);
89 catch (NotImplementedException
$e) {
91 if (isset($actionClass) && method_exists($actionClass, 'fields')) {
92 $values = $actionClass->fields();
95 $values = $this->getRecords();
97 $this->formatResults($values);
98 $this->queryArray($values, $result);
102 * Ensure every result contains, at minimum, the array keys as defined in $this->fields.
104 * Attempt to set some sensible defaults for some fields.
106 * Format option lists.
108 * In most cases it's not necessary to override this function, even if your entity is really weird.
109 * Instead just override $this->fields and this function will respect that.
111 * @param array $values
113 protected function formatResults(&$values) {
114 $fields = array_column($this->fields(), 'name');
115 // Enforce field permissions
116 if ($this->checkPermissions
) {
117 foreach ($values as $key => $field) {
118 if (!empty($field['permission']) && !\CRM_Core_Permission
::check($field['permission'])) {
119 unset($values[$key]);
123 foreach ($values as &$field) {
124 $defaults = array_intersect_key([
125 'title' => empty($field['name']) ?
NULL : ucwords(str_replace('_', ' ', $field['name'])),
126 'entity' => $this->getEntityName(),
129 'options' => !empty($field['pseudoconstant']),
130 'data_type' => \CRM_Utils_Array
::value('type', $field, 'String'),
131 ], array_flip($fields));
133 $field['label'] = $field['label'] ??
$field['title'];
134 if (isset($defaults['options'])) {
135 $field['options'] = $this->formatOptionList($field['options']);
137 $field +
= array_fill_keys($fields, NULL);
142 * Transforms option list into the format specified in $this->loadOptions
147 private function formatOptionList($options) {
148 if (!$this->loadOptions ||
!is_array($options)) {
149 return (bool) $options;
155 $first = reset($options);
156 // Flat array requested
157 if ($this->loadOptions
=== TRUE) {
158 // Convert non-associative to flat array
159 if (is_array($first) && isset($first['id'])) {
160 foreach ($options as $option) {
161 $formatted[$option['id']] = $option['label'] ??
$option['name'] ??
$option['id'];
167 // Non-associative array of multiple properties requested
168 foreach ($options as $id => $option) {
169 // Transform a flat list
170 if (!is_array($option)) {
177 $formatted[] = array_intersect_key($option, array_flip($this->loadOptions
));
185 public function getAction() {
186 // For actions that build on top of other actions, return fields for the simpler action
189 'replace' => 'create',
191 return $sub[$this->action
] ??
$this->action
;
195 * Add an item to the values array
196 * @param string $fieldName
197 * @param mixed $value
200 public function addValue(string $fieldName, $value) {
201 $this->values
[$fieldName] = $value;
206 * @param bool $includeCustom
209 public function setIncludeCustom(bool $includeCustom) {
210 // Be forgiving if the param doesn't exist and don't throw an exception
211 if (property_exists($this, 'includeCustom')) {
212 $this->includeCustom
= $includeCustom;
217 public function fields() {
221 'data_type' => 'String',
222 'description' => ts('Unique field identifier'),
226 'data_type' => 'String',
227 'description' => ts('Technical name of field, shown in API and exports'),
231 'data_type' => 'String',
232 'description' => ts('User-facing label, shown on most forms and displays'),
235 'name' => 'description',
236 'data_type' => 'String',
237 'description' => ts('Explanation of the purpose of the field'),
240 'name' => 'default_value',
241 'data_type' => 'String',
244 'name' => 'required',
245 'data_type' => 'Boolean',
248 'name' => 'required_if',
249 'data_type' => 'String',
253 'data_type' => 'Array',
256 'name' => 'data_type',
257 'data_type' => 'String',
259 'Integer' => ts('Integer'),
260 'Boolean' => ts('Boolean'),
261 'String' => ts('String'),
262 'Text' => ts('Text'),
263 'Date' => ts('Date'),
264 'Timestamp' => ts('Timestamp'),
265 'Array' => ts('Array'),
269 'name' => 'input_type',
270 'data_type' => 'String',
272 'Text' => ts('Text'),
273 'Number' => ts('Number'),
274 'Select' => ts('Select'),
275 'CheckBox' => ts('CheckBox'),
276 'Radio' => ts('Radio'),
277 'Date' => ts('Date'),
278 'File' => ts('File'),
279 'EntityRef' => ts('EntityRef'),
280 'ChainSelect' => ts('ChainSelect'),
284 'name' => 'input_attrs',
285 'data_type' => 'Array',
288 'name' => 'fk_entity',
289 'data_type' => 'String',
292 'name' => 'serialize',
293 'data_type' => 'Integer',
297 'data_type' => 'String',
300 'name' => 'readonly',
301 'data_type' => 'Boolean',