Civi/Api4/Generic/Result.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2020                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27
  28 namespace Civi\Api4\Generic;
  29
  30 /**
  31  * Container for api results.
  32  */
  33 class Result extends \ArrayObject {
  34   /**
  35    * @var string
  36    */
  37   public $entity;
  38   /**
  39    * @var string
  40    */
  41   public $action;
  42   /**
  43    * Api version
  44    * @var int
  45    */
  46   public $version = 4;
  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     $count = parent::count();
 115     if ($count == 1 && is_array($this->first()) && array_keys($this->first()) == ['row_count']) {
 116       return $this->first()['row_count'];
 117     }
 118     return $count;
 119   }
 120
 121   /**
 122    * Reduce each result to one field
 123    *
 124    * @param $name
 125    * @return array
 126    */
 127   public function column($name) {
 128     return array_column($this->getArrayCopy(), $name, $this->indexedBy);
 129   }
 130
 131 }