From 14a2140fc6a63c07dd7e359b60e171b1671dc268 Mon Sep 17 00:00:00 2001
From: Noah Miller <nm@lemnisc.us>
Date: Sat, 14 Oct 2023 13:27:59 -0400
Subject: [PATCH] Document and test unique behavior of CRM_Utils_Array::value()

---
 CRM/Utils/Array.php                   | 13 ++++++++-----
 tests/phpunit/CRM/Utils/ArrayTest.php | 15 +++++++++++++++
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/CRM/Utils/Array.php b/CRM/Utils/Array.php
index f1e2fd0ada..b96b4bbc63 100644
--- a/CRM/Utils/Array.php
+++ b/CRM/Utils/Array.php
@@ -43,18 +43,22 @@ class CRM_Utils_Array {
   }
 
   /**
-   * Returns $list[$key] if such element exists, or a default value otherwise.
+   * Returns $list[$key] if such element exists, or $default otherwise.
    *
-   * If $list is not actually an array at all, then the default value is
-   * returned. We hope to deprecate this behaviour.
+   * If $list is not an array or ArrayAccess object, $default is returned.
    *
+   * This function behaves exactly like:
+   *   $list[$key] ?? $default
+   * except that when $list[$key] exists and is NULL, this function will always
+   * return NULL.
    *
    * @param string $key
    *   Key value to look up in the array.
    * @param array|ArrayAccess $list
    *   Array from which to look up a value.
    * @param mixed $default
-   *   (optional) Value to return $list[$key] does not exist.
+   *   (optional) Value to return when $list[$key] does not exist. If $default
+   *   is not specified, NULL is used.
    *
    * @return mixed
    *   Can return any type, since $list might contain anything.
@@ -64,7 +68,6 @@ class CRM_Utils_Array {
       return array_key_exists($key, $list) ? $list[$key] : $default;
     }
     if ($list instanceof ArrayAccess) {
-      // ArrayAccess requires offsetExists is implemented for the equivalent to array_key_exists.
       return $list->offsetExists($key) ? $list[$key] : $default;
     }
     // @todo - eliminate these from core & uncomment this line.
diff --git a/tests/phpunit/CRM/Utils/ArrayTest.php b/tests/phpunit/CRM/Utils/ArrayTest.php
index 5d2e152faa..9485e91bcb 100644
--- a/tests/phpunit/CRM/Utils/ArrayTest.php
+++ b/tests/phpunit/CRM/Utils/ArrayTest.php
@@ -513,4 +513,19 @@ class CRM_Utils_ArrayTest extends CiviUnitTestCase {
     $this->assertEquals(0, $todoCount);
   }
 
+  public function testValue() {
+    $list = ['a' => 'apple', 'b' => 'banana', 'c' => NULL];
+
+    // array key exists; value is not null
+    $this->assertEquals('apple', CRM_Utils_Array::value('a', $list, 'fruit'));
+
+    // array key does not exist
+    $this->assertEquals('fruit', CRM_Utils_Array::value(999, $list, 'fruit'));
+
+    // array key exists; value is null
+    // This is the one situation in which the function's behavior differs from
+    // that of PHP's null-coalescing operator (??)
+    $this->assertEquals(NULL, CRM_Utils_Array::value('c', $list, 'fruit'));
+  }
+
 }
-- 
2.25.1