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();
127 * @param string $fieldName
129 * @param mixed $value
130 * @param bool $isExpression
132 * @throws \API_Exception
134 public function addWhere(string $fieldName, string $op, $value = NULL, bool $isExpression = FALSE) {
135 if (!in_array($op, CoreUtil
::getOperators())) {
136 throw new \
API_Exception('Unsupported operator');
138 $this->where
[] = [$fieldName, $op, $value, $isExpression];
145 public function getGroupBy(): array {
146 return $this->groupBy
;
150 * @param array $groupBy
153 public function setGroupBy(array $groupBy) {
154 $this->groupBy
= $groupBy;
159 * @param string $field
162 public function addGroupBy(string $field) {
163 $this->groupBy
[] = $field;
168 * @param string $expr
170 * @param mixed $value
172 * @throws \API_Exception
174 public function addHaving(string $expr, string $op, $value = NULL) {
175 if (!in_array($op, CoreUtil
::getOperators())) {
176 throw new \
API_Exception('Unsupported operator');
178 $this->having
[] = [$expr, $op, $value];
183 * @param string $entity
184 * @param string|bool $type
185 * @param string $bridge
186 * @param array ...$conditions
187 * @return DAOGetAction
189 public function addJoin(string $entity, $type = 'LEFT', $bridge = NULL, ...$conditions): DAOGetAction
{
191 array_unshift($conditions, $bridge);
193 array_unshift($conditions, $entity, $type);
194 $this->join
[] = $conditions;
200 * @return DAOGetAction
202 public function setJoin(array $join): DAOGetAction
{
210 public function getJoin(): array {