Civi/Api4/Generic/DAOGetAction.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\Api4\Query\Api4SelectQuery;
  23
  24 /**
  25  * Retrieve $ENTITIES based on criteria specified in the `where` parameter.
  26  *
  27  * Use the `select` param to determine which fields are returned, defaults to `[*]`.
  28  *
  29  * Perform joins on other related entities using a dot notation.
  30  *
  31  * @method $this setHaving(array $clauses)
  32  * @method array getHaving()
  33  */
  34 class DAOGetAction extends AbstractGetAction {
  35   use Traits\DAOActionTrait;
  36
  37   /**
  38    * Fields to return. Defaults to all non-custom fields `[*]`.
  39    *
  40    * Use the dot notation to perform joins in the select clause, e.g. selecting `['*', 'contact.*']` from `Email::get()`
  41    * will select all fields for the email + all fields for the related contact.
  42    *
  43    * @var array
  44    * @inheritDoc
  45    */
  46   protected $select = [];
  47
  48   /**
  49    * Joins to other entities.
  50    *
  51    * @var array
  52    */
  53   protected $join = [];
  54
  55   /**
  56    * Field(s) by which to group the results.
  57    *
  58    * @var array
  59    */
  60   protected $groupBy = [];
  61
  62   /**
  63    * Clause for filtering results after grouping and filters are applied.
  64    *
  65    * Each expression should correspond to an item from the SELECT array.
  66    *
  67    * @var array
  68    */
  69   protected $having = [];
  70
  71   public function _run(Result $result) {
  72     $this->setDefaultWhereClause();
  73     $this->expandSelectClauseWildcards();
  74     $result->exchangeArray($this->getObjects());
  75   }
  76
  77   /**
  78    * @return array|int
  79    */
  80   protected function getObjects() {
  81     $query = new Api4SelectQuery($this);
  82
  83     $result = $query->run();
  84     if (is_array($result)) {
  85       \CRM_Utils_API_HTMLInputCoder::singleton()->decodeRows($result);
  86     }
  87     return $result;
  88   }
  89
  90   /**
  91    * @return array
  92    */
  93   public function getGroupBy(): array {
  94     return $this->groupBy;
  95   }
  96
  97   /**
  98    * @param array $groupBy
  99    * @return $this
 100    */
 101   public function setGroupBy(array $groupBy) {
 102     $this->groupBy = $groupBy;
 103     return $this;
 104   }
 105
 106   /**
 107    * @param string $field
 108    * @return $this
 109    */
 110   public function addGroupBy(string $field) {
 111     $this->groupBy[] = $field;
 112     return $this;
 113   }
 114
 115   /**
 116    * @param string $expr
 117    * @param string $op
 118    * @param mixed $value
 119    * @return $this
 120    * @throws \API_Exception
 121    */
 122   public function addHaving(string $expr, string $op, $value = NULL) {
 123     if (!in_array($op, \CRM_Core_DAO::acceptedSQLOperators())) {
 124       throw new \API_Exception('Unsupported operator');
 125     }
 126     $this->having[] = [$expr, $op, $value];
 127     return $this;
 128   }
 129
 130   /**
 131    * @param string $entity
 132    * @param bool $required
 133    * @param array ...$conditions
 134    * @return DAOGetAction
 135    */
 136   public function addJoin(string $entity, bool $required = FALSE, ...$conditions): DAOGetAction {
 137     array_unshift($conditions, $entity, $required);
 138     $this->join[] = $conditions;
 139     return $this;
 140   }
 141
 142   /**
 143    * @param array $join
 144    * @return DAOGetAction
 145    */
 146   public function setJoin(array $join): DAOGetAction {
 147     $this->join = $join;
 148     return $this;
 149   }
 150
 151   /**
 152    * @return array
 153    */
 154   public function getJoin(): array {
 155     return $this->join;
 156   }
 157
 158 }