From 4c6ad36a8268995ee2e1daf9b25b4bcc6b436ece Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Tue, 27 Oct 2020 19:44:41 -0700
Subject: [PATCH] APIv4 - Add $result->single() helper

---
 Civi/Api4/Generic/Result.php                  | 26 +++++++++++++++++++
 .../phpunit/api/v4/Action/ContactGetTest.php  | 10 +++++++
 2 files changed, 36 insertions(+)

diff --git a/Civi/Api4/Generic/Result.php b/Civi/Api4/Generic/Result.php
index afc30c217a..77720c9685 100644
--- 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
diff --git a/tests/phpunit/api/v4/Action/ContactGetTest.php b/tests/phpunit/api/v4/Action/ContactGetTest.php
index 3fc8f6928f..7524a2db83 100644
--- a/tests/phpunit/api/v4/Action/ContactGetTest.php
+++ b/tests/phpunit/api/v4/Action/ContactGetTest.php
@@ -88,6 +88,16 @@ class ContactGetTest extends \api\v4\UnitTestCase {
     $limit2 = Contact::get(FALSE)->setLimit(2)->addSelect('sort_name', 'row_count')->execute();
     $this->assertCount(2, (array) $limit2);
     $this->assertCount($num, $limit2);
+    try {
+      $limit2->single();
+    }
+    catch (\API_Exception $e) {
+      $this->assertRegExp(';Expected to find one Contact record;', $e->getMessage());
+    }
+    $limit1 = Contact::get(FALSE)->setLimit(1)->execute();
+    $this->assertCount(1, (array) $limit1);
+    $this->assertCount(1, $limit1);
+    $this->assertTrue(!empty($limit1->single()['sort_name']));
   }
 
 }
-- 
2.25.1