PHP 8.4: Функции array_find, array_find_key, array_any и array_all

Новые функции предоставляют удобные подходы для таких распространённых операций, как поиск элемента массива, соответствующего определённому критерию (проверяется в предоставленном обратном вызове), и проверка соответствия любого или всех элементов массива определённому критерию.

• Новые функции PHP 8.4 для поиска элементов массива с помощью функции обратного вызова:
  • array_find: Возвращает значение первого элемента из массива, для которого обратный вызов возвращает true; null в противном случае.
  • array_find_key: Возвращает ключ первого элемента из массива, для которого обратный вызов возвращает true; null в противном случае.
• Новые функции PHP 8.4 для определения того, все ли элементы прошли проверку обратным вызовом:
  • array_all: Проверяет, возвращает ли обратный вызов true для всех элементов массива.
  • array_any: Проверяет, возвращает ли обратный вызов true для любого из элементов массива.

Новая функция array_find

Функция array_find возвращает значение первого элемента из массива, для которого обратный вызов вернул true. Если ни один из элементов не вернул true, функция array_find возвращает null.

Синопсис функции

/**
 * 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

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"

Новая функция array_find_key

Функция array_find_key аналогична функции array_find, но возвращает ключ первого элемента из массива, для которого обратный вызов вернул true. Если ни один из элементов не вернул true, функция array_find_key возвращает null.

Синопсис функции

/**
 * 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

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"

Новая функция array_all

Функция array_all принимает в качестве аргументов массив и обратный вызов, и возвращает true, если все элементы массива возвращают true в обратном вызове.

Функция обратного вызова вызывается со значением ($value) и ключом ($key) каждого элемента переданного массива.

array_all возвращает true для пустых массивов ([]).

Синопсис функции

/**
 * 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

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

Новая функция array_any

Функция array_any аналогична функции array_all. Она принимает в качестве аргументов массив и обратный вызов, и возвращает true, если любой из элементов массива возвращает true при передаче в обратный вызов.

Функция обратного вызова вызывается со значением ($value) и ключом ($key) каждого элемента переданного массива. После того как первый элемент вернёт true из функции обратного вызова, функция обратного вызова не будет вызываться для остальных элементов массива.

array_any возвращает false для пустых массивов ([]).

Синопсис функции

/**
 * 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

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

Влияние на обратную совместимость

Функции array_find, array_find_key, array_all и array_any — новые функции, добавленные в глобальное пространство имён. Если не существует пользовательских функций с такими же именами, это изменение не должно вызвать проблем с обратной совместимостью.

Новые функции могут быть реализованы и в пользовательском PHP.

Пакет polyfills/array-find предоставляет PHP-полифилл для функций array_find, array_find_key, array_all и array_any, поддерживающий PHP 7.1 и более поздние версии.

Следующая команда Composer устанавливает его:

composer require polyfills/array-find

• RFC
• Реализация