[RFC] Implement array_first() and array_last()

nielsdos · nielsdos · commit ab1145e47fce · 2025-05-06T20:33:47.000+02:00
diff --git a/NEWS b/NEWS
@@ -211,6 +211,7 @@ PHP                                                                        NEWS
     (Michael Orlitzky).
   . Fixed bug GH-18062 (is_callable(func(...), callable_name: $name) for first
     class callables returns wrong name). (timwolla)
+  . Added array_first() and array_last(). (nielsdos)
 
 - Streams:
   . Fixed bug GH-16889 (stream_select() timeout useless for pipes on Windows).
diff --git a/UPGRADING b/UPGRADING
@@ -356,6 +356,10 @@ PHP 8.5 UPGRADE NOTES
   . ReflectionConstant::getAttributes() was introduced.
     RFC: https://wiki.php.net/rfc/attributes-on-constants
 
+- Standard:
+  . Added array_first() and array_last().
+    RFC: https://wiki.php.net/rfc/array_first_last
+
 ========================================
 7. New Classes and Interfaces
 ========================================
diff --git a/ext/standard/array.c b/ext/standard/array.c
@@ -4513,6 +4513,32 @@ PHP_FUNCTION(array_key_last)
 }
 /* }}} */
 
+PHP_FUNCTION(array_first)
+{
+	HashTable *array;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_ARRAY_HT(array)
+	ZEND_PARSE_PARAMETERS_END();
+
+	ZEND_HASH_FOREACH_VAL(array, zval *zv) {
+		RETURN_COPY_DEREF(zv);
+	} ZEND_HASH_FOREACH_END();
+}
+
+PHP_FUNCTION(array_last)
+{
+	HashTable *array;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_ARRAY_HT(array)
+	ZEND_PARSE_PARAMETERS_END();
+
+	ZEND_HASH_REVERSE_FOREACH_VAL(array, zval *zv) {
+		RETURN_COPY_DEREF(zv);
+	} ZEND_HASH_FOREACH_END();
+}
+
 /* {{{ Return just the values from the input array */
 PHP_FUNCTION(array_values)
 {
diff --git a/ext/standard/basic_functions.stub.php b/ext/standard/basic_functions.stub.php
@@ -1712,6 +1712,16 @@ function array_key_first(array $array): int|string|null {}
  */
 function array_key_last(array $array): int|string|null {}
 
+/**
+ * @compile-time-eval
+ */
+function array_first(array $array): mixed {}
+
+/**
+ * @compile-time-eval
+ */
+function array_last(array $array): mixed {}
+
 /**
  * @return array<int, mixed|ref>
  * @compile-time-eval
diff --git a/ext/standard/basic_functions_arginfo.h b/ext/standard/basic_functions_arginfo.h
diff --git a/ext/standard/tests/array/array_first_last.phpt b/ext/standard/tests/array/array_first_last.phpt
@@ -0,0 +1,53 @@
+--TEST--
+array_first()/array_last()
+--FILE--
+<?php
+$str = "hello world";
+
+$test_cases = [
+    ["single element"],
+    [&$str, 1],
+    [1, &$str],
+    [1 => 1, 0 => 0, 3 => 3, 2 => 2],
+    [100 => []],
+    [new stdClass, false],
+    [true, new stdClass],
+];
+
+foreach ($test_cases as $test_case) {
+    // Output the checked values
+    echo "--- Testing: ", json_encode($test_case), " ---\n";
+    echo "First: ", json_encode(array_first($test_case)), "\n";
+    echo "Last: ", json_encode(array_last($test_case)), "\n";
+
+    // Sanity check consistency with array_key_first()/array_key_last()
+    if (array_first($test_case) !== $test_case[array_key_first($test_case)]) {
+        throw new Error("Key first and value first inconsistency");
+    }
+    if (array_last($test_case) !== $test_case[array_key_last($test_case)]) {
+        throw new Error("Key last and value last inconsistency");
+    }
+}
+?>
+--EXPECT--
+--- Testing: ["single element"] ---
+First: "single element"
+Last: "single element"
+--- Testing: ["hello world",1] ---
+First: "hello world"
+Last: 1
+--- Testing: [1,"hello world"] ---
+First: 1
+Last: "hello world"
+--- Testing: {"1":1,"0":0,"3":3,"2":2} ---
+First: 1
+Last: 2
+--- Testing: {"100":[]} ---
+First: []
+Last: []
+--- Testing: [{},false] ---
+First: {}
+Last: false
+--- Testing: [true,{}] ---
+First: true
+Last: {}
diff --git a/ext/standard/tests/array/array_first_last_errors.phpt b/ext/standard/tests/array/array_first_last_errors.phpt
@@ -0,0 +1,20 @@
+--TEST--
+array_first()/array_last() error cases
+--FILE--
+<?php
+var_dump(array_first([]));
+var_dump(array_last([]));
+
+$array = [1, 2, 3];
+unset($array[0]);
+unset($array[1]);
+unset($array[2]);
+
+var_dump(array_first($array));
+var_dump(array_last($array));
+?>
+--EXPECT--
+NULL
+NULL
+NULL
+NULL
