Civi/Api4/Generic/Result.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 namespace Civi\Api4\Generic;
  13
  14 /**
  15  * Container for api results.
  16  *
  17  * The Result object has three functions:
  18  *
  19  *  1. Store the results of the API call (accessible via ArrayAccess).
  20  *  2. Store metadata like the Entity & Action names.
  21  *     - Note: some actions extend the Result object to store extra metadata.
  22  *       For example, BasicReplaceAction returns ReplaceResult which includes the additional $deleted property to list any items deleted by the operation.
  23  *  3. Provide convenience methods like `$result->first()` and `$result->indexBy($field)`.
  24  */
  25 class Result extends \ArrayObject implements \JsonSerializable {
  26   /**
  27    * @var string
  28    */
  29   public $entity;
  30   /**
  31    * @var string
  32    */
  33   public $action;
  34   /**
  35    * @var array
  36    */
  37   public $debug;
  38   /**
  39    * Api version
  40    * @var int
  41    */
  42   public $version = 4;
  43   /**
  44    * @var int
  45    */
  46   public $rowCount;
  47
  48   private $indexedBy;
  49
  50   /**
  51    * Return first result.
  52    * @return array|null
  53    */
  54   public function first() {
  55     foreach ($this as $values) {
  56       return $values;
  57     }
  58     return NULL;
  59   }
  60
  61   /**
  62    * Return last result.
  63    * @return array|null
  64    */
  65   public function last() {
  66     $items = $this->getArrayCopy();
  67     return array_pop($items);
  68   }
  69
  70   /**
  71    * @param int $index
  72    * @return array|null
  73    */
  74   public function itemAt($index) {
  75     $length = $index < 0 ? 0 - $index : $index + 1;
  76     if ($length > count($this)) {
  77       return NULL;
  78     }
  79     return array_slice(array_values($this->getArrayCopy()), $index, 1)[0];
  80   }
  81
  82   /**
  83    * Re-index the results array (which by default is non-associative)
  84    *
  85    * Drops any item from the results that does not contain the specified key
  86    *
  87    * @param string $key
  88    * @return $this
  89    * @throws \API_Exception
  90    */
  91   public function indexBy($key) {
  92     $this->indexedBy = $key;
  93     if (count($this)) {
  94       $newResults = [];
  95       foreach ($this as $values) {
  96         if (isset($values[$key])) {
  97           $newResults[$values[$key]] = $values;
  98         }
  99       }
 100       if (!$newResults) {
 101         throw new \API_Exception("Key $key not found in api results");
 102       }
 103       $this->exchangeArray($newResults);
 104     }
 105     return $this;
 106   }
 107
 108   /**
 109    * Returns the number of results
 110    *
 111    * @return int
 112    */
 113   public function count() {
 114     return $this->rowCount ?? parent::count();
 115   }
 116
 117   /**
 118    * Reduce each result to one field
 119    *
 120    * @param $name
 121    * @return array
 122    */
 123   public function column($name) {
 124     return array_column($this->getArrayCopy(), $name, $this->indexedBy);
 125   }
 126
 127   /**
 128    * @return array
 129    */
 130   public function jsonSerialize() {
 131     return $this->getArrayCopy();
 132   }
 133
 134 }