Civi/Api4/Generic/BasicGetAction.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 use Civi\Api4\Utils\FormattingUtil;
  24
  25 /**
  26  * Retrieve $ENTITIES based on criteria specified in the `where` parameter.
  27  *
  28  * Use the `select` param to determine which fields are returned, defaults to `[*]`.
  29  */
  30 class BasicGetAction extends AbstractGetAction {
  31   use Traits\ArrayQueryActionTrait;
  32
  33   /**
  34    * @var callable
  35    *   Function(BasicGetAction $thisAction): array[]
  36    */
  37   private $getter;
  38
  39   /**
  40    * Basic Get constructor.
  41    *
  42    * @param string $entityName
  43    * @param string $actionName
  44    * @param callable $getter
  45    */
  46   public function __construct($entityName, $actionName, $getter = NULL) {
  47     parent::__construct($entityName, $actionName);
  48     $this->getter = $getter;
  49   }
  50
  51   /**
  52    * Fetch results from the getter then apply filter/sort/select/limit.
  53    *
  54    * @param \Civi\Api4\Generic\Result $result
  55    */
  56   public function _run(Result $result) {
  57     $this->setDefaultWhereClause();
  58     $this->expandSelectClauseWildcards();
  59     $values = $this->getRecords();
  60     $this->formatRawValues($values);
  61     $this->queryArray($values, $result);
  62   }
  63
  64   /**
  65    * BasicGet is a general-purpose get action for non-DAO-based entities.
  66    *
  67    * Useful for fetching records from files or other places.
  68    * Specify any php function to retrieve the records, and this class will
  69    * automatically filter, sort, select & limit the raw data from the callback.
  70    *
  71    * This action is implemented in one of two ways:
  72    * 1. Invoke this class directly by passing a callable ($getter) to the constructor. BasicEntity does this by default.
  73    *    The function is passed a copy of $this action as it's first argument.
  74    * 2. Extend this class and override this function.
  75    *
  76    * Either way, this function should return an array of arrays, each representing one retrieved object.
  77    *
  78    * The simplest thing for your getter function to do is return every full record
  79    * and allow this class to automatically do the sorting and filtering.
  80    *
  81    * Sometimes however that may not be practical for performance reasons.
  82    * To optimize your getter, it can use the following helpers from $this:
  83    *
  84    * Use this->_itemsToGet() to match records to field values in the WHERE clause.
  85    * Note the WHERE clause can potentially be very complex and it is not recommended
  86    * to parse $this->where yourself.
  87    *
  88    * Use $this->_isFieldSelected() to check if a field value is called for - useful
  89    * if loading the field involves expensive calculations.
  90    *
  91    * Be careful not to make assumptions, e.g. if LIMIT 100 is specified and your getter "helpfully" truncates the list
  92    * at 100 without accounting for WHERE, ORDER BY and LIMIT clauses, the final filtered result may be very incorrect.
  93    *
  94    * @return array
  95    * @throws \Civi\API\Exception\NotImplementedException
  96    */
  97   protected function getRecords() {
  98     if (is_callable($this->getter)) {
  99       $this->addCallbackToDebugOutput($this->getter);
 100       return call_user_func($this->getter, $this);
 101     }
 102     throw new NotImplementedException('Getter function not found for api4 ' . $this->getEntityName() . '::' . $this->getActionName());
 103   }
 104
 105   /**
 106    * Evaluate :pseudoconstant suffix expressions and replace raw values with option values
 107    *
 108    * @param $records
 109    * @throws \API_Exception
 110    * @throws \CRM_Core_Exception
 111    */
 112   protected function formatRawValues(&$records) {
 113     // Pad $records and $fields with pseudofields
 114     $fields = $this->entityFields();
 115     foreach ($records as &$values) {
 116       foreach ($this->entityFields() as $field) {
 117         if (!empty($field['options'])) {
 118           foreach (FormattingUtil::$pseudoConstantSuffixes as $suffix) {
 119             $pseudofield = $field['name'] . ':' . $suffix;
 120             if (!isset($values[$pseudofield]) && isset($values[$field['name']]) && $this->_isFieldSelected($pseudofield)) {
 121               $values[$pseudofield] = $values[$field['name']];
 122               $fields[$pseudofield] = $field;
 123             }
 124           }
 125         }
 126       }
 127     }
 128     // Swap raw values with pseudoconstants
 129     FormattingUtil::formatOutputValues($records, $fields, $this->getEntityName(), $this->getActionName());
 130   }
 131
 132 }