APIv4 - Add $result->single() helper

[totten]

Overview

This is a developer-experience improvement for the common case where one uses APIv4 to work with exactly one record (e.g. because having fewer or more records indicates a violation of a pre-condition).

Before

I have found myself writing this guard several times:

$result = civicrm_api4('Foo', 'bar', [
  'whiz' => 123,
  'bang' => 456,
]);
if ($result->count() !== 1) {
  throw new Exception(sprintf("This operation is defined for exactly one result. Found %d records.", 
    $result->count()));
}
$record = $result->first();

Note that the Result object has a first() method, which you could call fluently. That would be clean/pretty. However, this is a soft method which does not complain if there are zero or multiple records.

After

If the situation calls for exactly one record, then use single():

$record = civicrm_api4('Foo', 'bar', [
  'whiz' => 123,
  'bang' => 456,
])->single();

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[seamuslee001]

I like this but will leave for @colemanw to comment

[colemanw]

There is already something very similar:

$result = civicrm_api4('Foo', 'bar', [...], 0);

The 4th param is $index and in this case we're requesting the item at index 0. An exception will be thrown if no items are found. The only difference between this and your ->single() method is that an exception will not be thrown if 2 or more items are found (the first one will be returned without complaint). I've found that serves my purposes well enough, but sure we can merge this if you like.

[eileenmcnaughton]

OK - so no objection from @colemanw & it's a yes from me. Lock it in caller