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  * $Id$
  18  *
  19  */
  20
  21
  22 namespace Civi\Api4\Generic;
  23
  24 use Civi\API\Exception\NotImplementedException;
  25
  26 /**
  27  * Retrieve items based on criteria specified in the 'where' param.
  28  *
  29  * Use the 'select' param to determine which fields are returned, defaults to *.
  30  */
  31 class BasicGetAction extends AbstractGetAction {
  32   use Traits\ArrayQueryActionTrait;
  33
  34   /**
  35    * @var callable
  36    *
  37    * Function(BasicGetAction $thisAction) => array<array>
  38    */
  39   private $getter;
  40
  41   /**
  42    * Basic Get constructor.
  43    *
  44    * @param string $entityName
  45    * @param string $actionName
  46    * @param callable $getter
  47    */
  48   public function __construct($entityName, $actionName, $getter = NULL) {
  49     parent::__construct($entityName, $actionName);
  50     $this->getter = $getter;
  51   }
  52
  53   /**
  54    * Fetch results from the getter then apply filter/sort/select/limit.
  55    *
  56    * @param \Civi\Api4\Generic\Result $result
  57    */
  58   public function _run(Result $result) {
  59     $this->setDefaultWhereClause();
  60     $values = $this->getRecords();
  61     $result->exchangeArray($this->queryArray($values));
  62   }
  63
  64   /**
  65    * This Basic Get class is a general-purpose api for non-DAO-based entities.
  66    *
  67    * Useful for fetching records from files or other places.
  68    * You can specify any php function to retrieve the records, and this class will
  69    * automatically filter, sort, select & limit the raw data from your callback.
  70    *
  71    * You can implement this action in one of two ways:
  72    * 1. Use this class directly by passing a callable ($getter) to the constructor.
  73    * 2. Extend this class and override this function.
  74    *
  75    * Either way, this function should return an array of arrays, each representing one retrieved object.
  76    *
  77    * The simplest thing for your getter function to do is return every full record
  78    * and allow this class to automatically do the sorting and filtering.
  79    *
  80    * Sometimes however that may not be practical for performance reasons.
  81    * To optimize your getter, it can use the following helpers from $this:
  82    *
  83    * Use this->_itemsToGet() to match records to field values in the WHERE clause.
  84    * Note the WHERE clause can potentially be very complex and it is not recommended
  85    * to parse $this->where yourself.
  86    *
  87    * Use $this->_isFieldSelected() to check if a field value is called for - useful
  88    * if loading the field involves expensive calculations.
  89    *
  90    * Be careful not to make assumptions, e.g. if LIMIT 100 is specified and your getter "helpfully" truncates the list
  91    * at 100 without accounting for WHERE, ORDER BY and LIMIT clauses, the final filtered result may be very incorrect.
  92    *
  93    * @return array
  94    * @throws \Civi\API\Exception\NotImplementedException
  95    */
  96   protected function getRecords() {
  97     if (is_callable($this->getter)) {
  98       return call_user_func($this->getter, $this);
  99     }
 100     throw new NotImplementedException('Getter function not found for api4 ' . $this->getEntityName() . '::' . $this->getActionName());
 101   }
 102
 103 }