PHP: rfc:array_find

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: array_find ======
  * Version: 1.2.0
  * Date: 2024-04-07
  * Author: Joshua Rüsweg, josh@php.net
  * Status: Voting
  * First Published at: https://wiki.php.net/rfc/array_find
  * Discussion: https://externals.io/message/123015

===== Introduction =====

This RFC proposes the addition of new array functions: <php>array_find</php>, <php>array_find_key</php>, <php>array_any</php> and <php>array_all</php>, which are helper functions for common patterns of checking an array for the existence of elements matching a specific condition.

There are currently several functions processing arrays using a callback. However still missing are functions to find a single element matching a condition and the closely related functions of checking whether or not there are elements matching a condition. Implementing these functions in userland is relatively simple, but these functions are often required, leading to the wheel being reinvented over and over. Furthermore these type of functions are implemented in other programming languages like Rust, JavaScript or C++, too. Therefore there is a reason to include these functions as standard with the next PHP version. In addition, the implementation of these functions is quite similar to <php>array_filter</php> and relatively trivial to implement, so the maintenance effort should be low.

===== Proposal =====

This RFC proposes to add four new function, <php>array_find</php>, <php>array_find_key</php>, <php>array_any</php> and <php>array_all</php>.

==== array_find ====

<php>array_find</php> returns the value of the first element for which the <php>$callback</php> returns <php>true</php>. If no matching element is found the function returns <php>NULL</php>.

<PHP>
function array_find(array $array, callable $callback): mixed {
    foreach ($array as $key => $value) {
        if ($callback($value, $key)) {
            return $value;
        }
    }

    return null;
}
</PHP>

=== Parameters ===

<php>array $array</php>

The array that should be searched.

<php>callable $callback</php>

The callback function to call to check each element. The first parameter contains the value, the second parameter contains the corresponding key. If this function returns <php>true</php>, the value is returned from <php>array_find</php> and the callback will not be called for further elements.

=== Return Value ===

The function returns the value of the first element for which the <php>$callback</php> returns <php>true</php>. If no matching element is found the function returns <php>NULL</php>.

=== Examples ===

<PHP>
$array = [
    'a' => 'dog',
    'b' => 'cat',
    'c' => 'cow',
    'd' => 'duck',
    'e' => 'goose',
    'f' => 'elephant'
];

// Find the first animal with a name longer than 4 characters.
var_dump(array_find($array, function (string $value) {
    return strlen($value) > 4;
})); // string(5) "goose"

// Find the first animal whose name begins with f.
var_dump(array_find($array, function (string $value) {
    return str_starts_with($value, 'f');
})); // NULL

// Find the first animal where the array key is the first symbol of the animal.
var_dump(array_find($array, function (string $value, $key) {
   return $value[0] === $key;
})); // string(3) "cow"

// Find the first animal where the array key matching a RegEx.
var_dump(array_find($array, function ($value, $key) {
   return preg_match('/^([a-f])$/', $key);
})); // string(3) "dog"
</PHP>

==== array_find_key ====
<php>array_find_key</php> returns the key of the first element for which the <php>$callback</php> returns <php>true</php>. If no matching element is found the function returns <php>NULL</php>.

<PHP>
function array_find_key(array $array, callable $callback): mixed {
    foreach ($array as $key => $value) {
        if ($callback($value, $key)) {
            return $key;
        }
    }

    return null;
}
</PHP>

=== Parameters ===

<php>array $array</php>

The array that should be searched.

<php>callable $callback</php>

The callback function to call to check each element. The first parameter contains the value, the second parameter contains the corresponding key. If this function returns <php>true</php>, the key is returned from <php>array_find_key</php> and the callback will not be called for further elements.

=== Return Value ===
The function returns the key of the first element for which the <php>$callback</php> returns <php>true</php>. If no matching element is found the function returns <php>NULL</php>.

=== Examples ===

<PHP>
$array = [
    'a' => 'dog',
    'b' => 'cat',
    'c' => 'cow',
    'd' => 'duck',
    'e' => 'goose',
    'f' => 'elephant'
];

// Find the first animal with a name longer than 4 characters.
var_dump(array_find_key($array, function (string $value) {
    return strlen($value) > 4;
})); // string(1) "e"

// Find the first animal whose name begins with f.
var_dump(array_find_key($array, function (string $value) {
    return str_starts_with($value, 'f');
})); // NULL

// Find the first animal where the array key is the first symbol of the animal.
var_dump(array_find_key($array, function (string $value, $key) {
   return $value[0] === $key;
})); // string(1) "c"

// Find the first animal where the array key matching a RegEx.
var_dump(array_find_key($array, function (string $value, $key) {
   return preg_match('/^([a-f])$/', $key);
})); // string(1) "a"
</PHP>

==== array_any ====

<php>array_any</php> returns <php>true</php>, if <php>$callback</php> returns <php>true</php> for any element. Otherwise the function returns <php>false</php>.

<PHP>
function array_any(array $array, callable $callback): bool {
    foreach ($array as $key => $value) {
        if ($callback($value, $key)) {
            return true;
        }
    }

    return false;
}
</PHP>

=== Parameters ===

<php>array $array</php>

The array that should be searched.

<php>callable $callback</php>

The callback function to call to check each element. The first parameter contains the value, the second parameter contains the corresponding key. If this function returns <php>true</php>, <php>true</php> is returned from <php>array_any</php> and the callback will not be called for further elements.

=== Return Value ===

The function returns <php>true</php>, if there is at least one element for which <php>$callback</php> returns <php>true</php>. Otherwise the function returns <php>false</php>.

=== Examples ===

<PHP>
$array = [
    'a' => 'dog',
    'b' => 'cat',
    'c' => 'cow',
    'd' => 'duck',
    'e' => 'goose',
    'f' => 'elephant'
];

// Check, if any animal name is longer than 5 letters.
var_dump(array_any($array, function (string $value) {
    return strlen($value) > 5;
})); // bool(true)

// Check, if any animal name is shorter than 3 letters.
var_dump(array_any($array, function (string $value) {
    return strlen($value) < 3;
})); // bool(false)

// Check, if any array key is not a string.
var_dump(array_any($array, function (string $value, $key) {
   return !is_string($key);
})); // bool(false)
</PHP>

==== array_all ====

<php>array_all</php> returns <php>true</php>, if <php>$callback</php> returns <php>true</php> for all elements. Otherwise the function returns <php>false</php>.

<PHP>
function array_all(array $array, callable $callback): bool {
    foreach ($array as $key => $value) {
        if (!$callback($value, $key)) {
            return false;
        }
    }

    return true;
}
</PHP>

=== Parameters ===

<php>array $array</php>

The array that should be searched.

<php>callable $callback</php>

The callback function to call to check each element. The first parameter contains the value, the second parameter contains the corresponding key. If this function returns <php>false</php>, <php>false</php> is returned from <php>array_all</php> and the callback will not be called for further elements.

=== Return Value ===

The function returns <php>true</php>, if <php>$callback</php> returns <php>true</php> for all elements. Otherwise the function returns <php>false</php>.

=== Examples ===

<PHP>
$array = [
    'a' => 'dog',
    'b' => 'cat',
    'c' => 'cow',
    'd' => 'duck',
    'e' => 'goose',
    'f' => 'elephant'
];

// Check, if all animal names are shorter than 12 letters.
var_dump(array_all($array, function (string $value) {
    return strlen($value) < 12;
})); // bool(true)

// Check, if all animal names are longer than 5 letters.
var_dump(array_all($array, function (string $value) {
    return strlen($value) > 5;
})); // bool(false)

// Check, if all array keys are strings.
var_dump(array_all($array, function (string $value, $key) {
   return is_string($key);
})); // bool(true)
</PHP>

===== Backward Incompatible Changes =====

Functions created by the user and named <php>array_find</php>, <php>array_find_key</php>, <php>array_any</php> or <php>array_all</php> lead to a PHP error with the new version. A quick GitHub search shows, that there a [[https://github.com/search?q=language%3Aphp%20symbol%3Aarray_find&type=code|656 results]] defining the symbol <php>array_find</php>, [[https://github.com/search?q=language%3Aphp%20symbol%3Aarray_find_key&type=code|28 results]] defining the symbol <php>array_find_key</php>, [[https://github.com/search?q=language%3Aphp%20symbol%3Aarray_any&type=code|127 results]] defining the symbol <php>array_any</php> and [[https://github.com/search?q=language%3Aphp%20symbol%3Aarray_all&type=code|284 results]] defining the symbol <php>array_all</php> for the language PHP.

Looking at the search results I estimate about 30% of these results are functions that are not located in a namespace, are not part of a class and are not false-positvies (e.g. the symbol is <php>db_array_all</php> instead of <php>array_all</php>).

===== Proposed PHP Version(s) =====

PHP 8.4

===== RFC Impact =====
==== To SAPIs ====

None.

==== To Existing Extensions ====

None.

==== To Opcache ====

None.

==== New Constants ====

None.

==== php.ini Defaults ====

None.

===== Open Issues =====

This function behaves differently to <php>array_filter</php>, because it always passes the value and the key to the callback. <php>array_filter</php> has a parameter for this to set which parameters are to be passed to the callback. <php>array_map</php> does not support the pass of the key at all, but support using more than one array, to pass a various number of parameters to the callback. With closures, omitting a parameter is now possible without any problems, therefore, there is no reason to determine the choice of parameters for the callback.

===== Unaffected PHP Functionality =====

This RFC only adds two new functions to PHP and only affects previously defined functions which are named as the proposed functions.

===== Proposed Voting Choices =====

Each vote requires a 2/3 majority.

Voting started on 2024-05-15 and will end on 2024-05-29 15:00 UTC.

==== array_find()/array_find_key() ====

<doodle title="Add array_find() and array_find_key()?" auth="josh" voteType="single" closed="false" closeon="2024-05-29T15:00:00Z">
   * Yes
   * No
</doodle>


==== array_any()/array_all() ====

<doodle title="Add array_any() and array_all()?" auth="josh" voteType="single" closed="false" closeon="2024-05-29T15:00:00Z">
   * Yes
   * No
</doodle>


===== Implementation =====

https://github.com/php/php-src/pull/14108


===== References =====

  * GitHub currently has [[https://github.com/search?q=language%3Aphp%20symbol%3Aarray_find&type=code|656 results]] for <php>array_find</php> and Laravel implements this feature by default with [[https://github.com/laravel/framework/blob/08acc925f1ec8e1c41a54774a36720f506c5b5a8/src/Illuminate/Collections/Arr.php#L193|Arr:first]].
  * https://en.cppreference.com/w/cpp/algorithm/find
  * https://en.cppreference.com/w/cpp/algorithm/all_any_none_of
  * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find
  * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every
  * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some
  * https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.find
  * https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.all
  * https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.any
Page Tools
