Civi/Api4/Generic/BasicGetFieldsAction.php

   1 <?php
   2
   3 /*
   4  +--------------------------------------------------------------------+
   5  | Copyright CiviCRM LLC. All rights reserved.                        |
   6  |                                                                    |
   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  +--------------------------------------------------------------------+
  11  */
  12
  13 /**
  14  *
  15  * @package CRM
  16  * @copyright CiviCRM LLC https://civicrm.org/licensing
  17  */
  18
  19
  20 namespace Civi\Api4\Generic;
  21
  22 use Civi\API\Exception\NotImplementedException;
  23
  24 /**
  25  * Lists information about fields for the $ENTITY entity.
  26  *
  27  * This field information is also known as "metadata."
  28  *
  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.
  32  *
  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()
  38  */
  39 class BasicGetFieldsAction extends BasicGetAction {
  40
  41   /**
  42    * Fetch option lists for fields?
  43    *
  44    * This parameter can be either a boolean or an array of attributes to return from the option list:
  45    *
  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).
  52    *
  53    * @var bool|array
  54    */
  55   protected $loadOptions = FALSE;
  56
  57   /**
  58    * Fields will be returned appropriate to the specified action (get, create, delete, etc.)
  59    *
  60    * @var string
  61    */
  62   protected $action = 'get';
  63
  64   /**
  65    * Fields will be returned appropriate to the specified values (e.g. ['contact_type' => 'Individual'])
  66    *
  67    * @var array
  68    */
  69   protected $values = [];
  70
  71   /**
  72    * To implement getFields for your own entity:
  73    *
  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().
  81    *
  82    * @param Result $result
  83    * @throws \Civi\API\Exception\NotImplementedException
  84    */
  85   public function _run(Result $result) {
  86     try {
  87       $actionClass = \Civi\API\Request::create($this->getEntityName(), $this->getAction(), ['version' => 4]);
  88     }
  89     catch (NotImplementedException $e) {
  90     }
  91     if (isset($actionClass) && method_exists($actionClass, 'fields')) {
  92       $values = $actionClass->fields();
  93     }
  94     else {
  95       $values = $this->getRecords();
  96     }
  97     $this->formatResults($values);
  98     $this->queryArray($values, $result);
  99   }
 100
 101   /**
 102    * Ensure every result contains, at minimum, the array keys as defined in $this->fields.
 103    *
 104    * Attempt to set some sensible defaults for some fields.
 105    *
 106    * Format option lists.
 107    *
 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.
 110    *
 111    * @param array $values
 112    */
 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]);
 120         }
 121       }
 122     }
 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(),
 127         'required' => FALSE,
 128         'readonly' => FALSE,
 129         'options' => !empty($field['pseudoconstant']),
 130         'data_type' => \CRM_Utils_Array::value('type', $field, 'String'),
 131       ], array_flip($fields));
 132       $field += $defaults;
 133       $field['label'] = $field['label'] ?? $field['title'];
 134       if (isset($defaults['options'])) {
 135         $field['options'] = $this->formatOptionList($field['options']);
 136       }
 137       $field += array_fill_keys($fields, NULL);
 138     }
 139   }
 140
 141   /**
 142    * Transforms option list into the format specified in $this->loadOptions
 143    *
 144    * @param $options
 145    * @return array|bool
 146    */
 147   private function formatOptionList($options) {
 148     if (!$this->loadOptions || !is_array($options)) {
 149       return (bool) $options;
 150     }
 151     if (!$options) {
 152       return $options;
 153     }
 154     $formatted = [];
 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'];
 162         }
 163         return $formatted;
 164       }
 165       return $options;
 166     }
 167     // Non-associative array of multiple properties requested
 168     foreach ($options as $id => $option) {
 169       // Transform a flat list
 170       if (!is_array($option)) {
 171         $option = [
 172           'id' => $id,
 173           'name' => $option,
 174           'label' => $option,
 175         ];
 176       }
 177       $formatted[] = array_intersect_key($option, array_flip($this->loadOptions));
 178     }
 179     return $formatted;
 180   }
 181
 182   /**
 183    * @return string
 184    */
 185   public function getAction() {
 186     // For actions that build on top of other actions, return fields for the simpler action
 187     $sub = [
 188       'save' => 'create',
 189       'replace' => 'create',
 190     ];
 191     return $sub[$this->action] ?? $this->action;
 192   }
 193
 194   /**
 195    * Add an item to the values array
 196    * @param string $fieldName
 197    * @param mixed $value
 198    * @return $this
 199    */
 200   public function addValue(string $fieldName, $value) {
 201     $this->values[$fieldName] = $value;
 202     return $this;
 203   }
 204
 205   /**
 206    * @param bool $includeCustom
 207    * @return $this
 208    */
 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;
 213     }
 214     return $this;
 215   }
 216
 217   public function fields() {
 218     return [
 219       [
 220         'name' => 'name',
 221         'data_type' => 'String',
 222         'description' => ts('Unique field identifier'),
 223       ],
 224       [
 225         'name' => 'title',
 226         'data_type' => 'String',
 227         'description' => ts('Technical name of field, shown in API and exports'),
 228       ],
 229       [
 230         'name' => 'label',
 231         'data_type' => 'String',
 232         'description' => ts('User-facing label, shown on most forms and displays'),
 233       ],
 234       [
 235         'name' => 'description',
 236         'data_type' => 'String',
 237         'description' => ts('Explanation of the purpose of the field'),
 238       ],
 239       [
 240         'name' => 'default_value',
 241         'data_type' => 'String',
 242       ],
 243       [
 244         'name' => 'required',
 245         'data_type' => 'Boolean',
 246       ],
 247       [
 248         'name' => 'required_if',
 249         'data_type' => 'String',
 250       ],
 251       [
 252         'name' => 'options',
 253         'data_type' => 'Array',
 254       ],
 255       [
 256         'name' => 'data_type',
 257         'data_type' => 'String',
 258         'options' => [
 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'),
 266         ],
 267       ],
 268       [
 269         'name' => 'input_type',
 270         'data_type' => 'String',
 271         'options' => [
 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'),
 281         ],
 282       ],
 283       [
 284         'name' => 'input_attrs',
 285         'data_type' => 'Array',
 286       ],
 287       [
 288         'name' => 'fk_entity',
 289         'data_type' => 'String',
 290       ],
 291       [
 292         'name' => 'serialize',
 293         'data_type' => 'Integer',
 294       ],
 295       [
 296         'name' => 'entity',
 297         'data_type' => 'String',
 298       ],
 299       [
 300         'name' => 'readonly',
 301         'data_type' => 'Boolean',
 302       ],
 303     ];
 304   }
 305
 306 }