PHP 8.4: New array_find, array_find_key, array_any, and array_all functions

Version8.4
TypeNew Feature

PHP 8.4 adds four new array functions to search and inspect array elements with a callback function: array_find, array_find_key, array_all, and array_any.

The new functions provide convenient approaches for common operations such as finding an array element that matches a certain criteria (checked as a provided callback), and checking if any or all of the array elements pass a certain criteria.

  • New PHP 8.4 functions to find array elements by a callback function:

    • array_find: Returns the value of the first element from the array for which the callback returns true; null otherwise.
    • array_find_key: Returns the key of the first element from the array for which the callback returns true; null otherwise.

  • New PHP 8.4 functions to find whether any or all elements pass a callback check:

    • array_all: Checks whether the callback returns true for all the array elements.
    • array_any: Checks whether the callback returns true for any of the array elements.

New array_find function

array_find function returns the value of the first element from the array for which the callback returns true. If none of the elements returned true, the array_find function returns null.

Function Synopsis

/**
 * Returns the VALUE of the first element from $array for which the
 *  $callback returns true. Returns NULL if no matching element is
 *  found.
 *
 * @param array $array The array that should be searched.
 * @param callable $callback The callback function to call to check
 *  each element. The first parameter contains the value ($value),
 *  the second parameter contains the corresponding key ($key).
 *  If this callback returns TRUE (or a truthy value), the value
 *  ($value) is returned immediately and the callback will not be
 *  called for further elements.
 *
 * @return mixed The function returns the value of the first
 *  element for which the $callback returns TRUE. NULL, if no
 *  matching element is found. Note that the matching element value
 *  itself could be NULL as well.
 */
function array_find(array $array, callable $callback): mixed {}

array_find usage examples

function is_even(int $value): bool {
    return $value % 2 === 0;
}

array_find([1, 2, 3, 4, 5], 'is_even');
// 2
array_find([1, 2, 3, 4, 5], fn($value) => $value % 2 === 0);
// 2
function is_key_numeric(mixed $value, mixed $key): bool {
    return is_numeric($key);
}

array_find(['a' => 'foo', 2 => 'bar'], 'is_key_numeric');
// "bar"

New array_find_key function

array_find_key function is similar to the array_find function, but it returns the key of the first element from the array for which the callback returns true. If none of the elements returned true, the array_find_key function returns null.

Function synopsis

/**
 * Returns the KEY of the first element from $array for which the
 *  $callback returns TRUE. If no matching element is found the
 *  function returns NULL.
 *
 * @param array $array The array that should be searched.
 * @param callable $callback The callback function to call to check
 *  each element. The first parameter contains the value ($value),
 *  the second parameter contains the corresponding key ($key). If
 *  this function returns TRUE, the key ($key) is returned
 *  immediately and the callback will not be called for further
 *  elements.
 *
 * @return mixed The key of the first element for which the
 *  $callback returns TRUE. NULL, If no matching element is found.
 */
function array_find_key(array $array, callable $callback): mixed {}

array_find_key usage examples

function is_even(int $value): bool {
    return $value % 2 === 0;
}

array_find_key(['foo' => 1, 'bar' => 2, 'baz' => 3], 'is_even');
// "bar"
array_find_key(
    ['foo' => 1, 'bar' => 2, 'baz' => 3],
    fn($value) => $value % 2 === 0
);
// "bar"
function is_key_numeric(mixed $value, mixed $key): bool {
    return is_numeric($key);
}

array_find_key(['a' => 'foo', 2 => 'bar'], 'is_key_numeric');
// "2"

New array_all function

The array_all function takes an array and a callback, and returns true if all of the elements in the array return true when passed to the callback.

The callback function is called with the value ($value) and key ($key) of each element of the given array.

array_all returns true on empty arrays ([]).

Function Synopsis

/**
 * Checks whether the $callback returns TRUE for ALL the array
 *  elements.
 *
 * @param array $array The array that should be searched.
 * @param callable $callback The callback function to call to check
 *  each element. The first parameter contains the value ($value), the
 *  second parameter contains the corresponding key. If this function
 *  returns FALSE (or any falsy value), FALSE is returned immediately
 *  and the $callback will not be called for further elements.
 *
 * @return bool TRUE, if $callback returns TRUE for all elements.
 *  FALSE otherwise.
 */
function array_all(array $array, callable $callback): bool {}

array_all usage examples

array_all(
    ['foo@example.com', 'bar@example.com', 'baz@example.com'],
    fn($value) => filter_var($value, FILTER_VALIDATE_EMAIL),
);
// true

array_all(
    ['foo@example.com', 'bar@example.com', 'baz'],
    fn($value) => filter_var($value, FILTER_VALIDATE_EMAIL),
);
// false
array_all(
    [1 => '', 2 => '', 3 => ''],
    fn($value, $key) => is_numeric($key),
);
// true

New array_any function

The array_any function is similar to the array_all function. It takes an array and a callback, and returns true if any of the elements in the array return true when passed to the callback.

The callback function is called with the value ($value) and key ($key) of each element of the given array. Once the first element returns true from the callback function, the callback function is not called on the rest of the array elements.

array_any returns false on empty arrays ([]).

Function Synopsis

/**
 * Checks whether the $callback returns TRUE for ANY of the array
 *  elements.
 *
 * @param array $array The array that should be searched.
 * @param callable $callback The callback function to call to check
 *  each element. The first parameter contains the value ($value), the
 *  second parameter contains the corresponding key ($key). If this
 *  function returns TRUE (or a truthy value), TRUE is returned
 *  immediately and the $callback will not be called for further
 *  elements.
 *
 * @return bool TRUE if there is at least one element for which
 *  $callback returns TRUE. FALSE otherwise.
 */
function array_any(array $array, callable $callback): bool {}

array_any usage examples

array_any(
    ['foo@example.com', 'https://php.watch', 'foobar'],
    fn($value) => filter_var($value, FILTER_VALIDATE_URL),
);
// true

array_all(
    ['https://php.watch', new stdClass()],
    fn($value) => filter_var($value, FILTER_VALIDATE_EMAIL),
);
// false
array_any(
    [1 => '', 'bar' => '', 'baz' => ''],
    fn($value, $key) => is_numeric($key),
);
// true

Backward Compatibility Impact

array_find, array_find_key, array_all, and array_any functions are new function added to the global namespace. Unless there are user-land functions with the same names, this change should not introduce any backward-compatibility issues.

The new functions can be trivially implemented in user-land PHP as well.

The polyfills/array_find package provides a PHP polyfill for the array_find, array_find_key, array_all, and array_any functions, supporting PHP 7.1 and later.

The following Composer command installs it:

composer require polyfills/array-find

Related Changes

RFC Discussion Implementation