Merge pull request #22992 from eileenmcnaughton/billingnot

[civicrm-core.git] / Civi / Api4 / Generic / Result.php

diff --git a/Civi/Api4/Generic/Result.php b/Civi/Api4/Generic/Result.php
index afc30c217ade1d5b7dde54284881ac457609ae4b..77720c9685737983e66abb378c5497d828701716 100644 (file)
--- a/Civi/Api4/Generic/Result.php
+++ b/Civi/Api4/Generic/Result.php
@@ -67,6 +67,32 @@ class Result extends \ArrayObject implements \JsonSerializable {
     return array_pop($items);
   }
 
+  /**
+   * Return the one-and-only result record.
+   *
+   * If there are too many or too few results, then throw an exception.
+   *
+   * @return array
+   * @throws \API_Exception
+   */
+  public function single() {
+    $result = NULL;
+    foreach ($this as $values) {
+      if ($result === NULL) {
+        $result = $values;
+      }
+      else {
+        throw new \API_Exception("Expected to find one {$this->entity} record, but there were multiple.");
+      }
+    }
+
+    if ($result === NULL) {
+      throw new \API_Exception("Expected to find one {$this->entity} record, but there were zero.");
+    }
+
+    return $result;
+  }
+
   /**
    * @param int $index
    * @return array|null