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