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 +--------------------------------------------------------------------+
13 namespace Civi\Api4\Generic
;
15 use Civi\Api4\Query\Api4SelectQuery
;
16 use Civi\Api4\Utils\CoreUtil
;
19 * Retrieve $ENTITIES based on criteria specified in the `where` parameter.
21 * Use the `select` param to determine which fields are returned, defaults to `[*]`.
23 * Perform joins on other related entities using a dot notation.
25 * @method $this setHaving(array $clauses)
26 * @method array getHaving()
28 class DAOGetAction
extends AbstractGetAction
{
29 use Traits\DAOActionTrait
;
32 * Fields to return. Defaults to all non-custom fields `['*']`.
34 * The keyword `"custom.*"` selects all custom fields. So to select all core + custom fields, select `['*', 'custom.*']`.
36 * Use the dot notation to perform joins in the select clause, e.g. selecting `['*', 'contact.*']` from `Email::get()`
37 * will select all fields for the email + all fields for the related contact.
42 protected $select = [];
45 * Joins to other entities.
47 * Each join is an array of properties:
50 * [Entity, Required, Bridge, [field, op, value]...]
53 * - `Entity`: the name of the api entity to join onto.
54 * - `Required`: `TRUE` for an `INNER JOIN`, `FALSE` for a `LEFT JOIN`.
55 * - `Bridge` (optional): Name of a Bridge to incorporate into the join.
56 * - `[field, op, value]...`: zero or more conditions for the ON clause, using the same nested format as WHERE and HAVING
57 * but with the difference that "value" is interpreted as an expression (e.g. can be the name of a field).
58 * Enclose literal values with quotes.
61 * @see \Civi\Api4\Generic\Traits\EntityBridge
66 * Field(s) by which to group the results.
70 protected $groupBy = [];
73 * Clause for filtering results after grouping and filters are applied.
75 * Each expression should correspond to an item from the SELECT array.
79 protected $having = [];
82 * @throws \API_Exception
83 * @throws \CRM_Core_Exception
85 public function _run(Result
$result) {
86 // Early return if table doesn't exist yet due to pending upgrade
87 $baoName = $this->getBaoName();
89 // In some cases (eg. site spin-up) the code may attempt to call the api before the entity name is registered.
90 throw new \
API_Exception("BAO for {$this->getEntityName()} is not available. This could be a load-order issue");
92 if (!$baoName::tableHasBeenAdded()) {
93 \Civi
::log()->warning("Could not read from {$this->getEntityName()} before table has been added. Upgrade required.", ['civi.tag' => 'upgrade_needed']);
97 $this->setDefaultWhereClause();
98 $this->expandSelectClauseWildcards();
99 $this->getObjects($result);
103 * @param \Civi\Api4\Generic\Result $result
105 protected function getObjects(Result
$result) {
106 $getCount = in_array('row_count', $this->getSelect());
107 $onlyCount = $this->getSelect() === ['row_count'];
110 $query = new Api4SelectQuery($this);
111 $rows = $query->run();
112 \CRM_Utils_API_HTMLInputCoder
::singleton()->decodeRows($rows);
113 $result->exchangeArray($rows);
114 // No need to fetch count if we got a result set below the limit
115 if (!$this->getLimit() ||
count($rows) < $this->getLimit()) {
116 $result->rowCount
= count($rows) +
$this->getOffset();
121 $query = new Api4SelectQuery($this);
122 $result->rowCount
= $query->getCount();
129 public function getGroupBy(): array {
130 return $this->groupBy
;
134 * @param array $groupBy
137 public function setGroupBy(array $groupBy) {
138 $this->groupBy
= $groupBy;
143 * @param string $field
146 public function addGroupBy(string $field) {
147 $this->groupBy
[] = $field;
152 * @param string $expr
154 * @param mixed $value
156 * @throws \API_Exception
158 public function addHaving(string $expr, string $op, $value = NULL) {
159 if (!in_array($op, CoreUtil
::getOperators())) {
160 throw new \
API_Exception('Unsupported operator');
162 $this->having
[] = [$expr, $op, $value];
167 * @param string $entity
168 * @param string|bool $type
169 * @param string $bridge
170 * @param array ...$conditions
171 * @return DAOGetAction
173 public function addJoin(string $entity, $type = 'LEFT', $bridge = NULL, ...$conditions): DAOGetAction
{
175 array_unshift($conditions, $bridge);
177 array_unshift($conditions, $entity, $type);
178 $this->join
[] = $conditions;
184 * @return DAOGetAction
186 public function setJoin(array $join): DAOGetAction
{
194 public function getJoin(): array {