PHP 8.4: Nuevas funciones array_find, array_find_key, array_any, y array_all

php.jpg
Solucionex
14
Ago 24

PHP 8.4 añade cuatro nuevas funciones de array para buscar e inspeccionar elementos de un array utilizando una función de callback: array_find, array_find_key, array_all, y array_any.

Estas nuevas funciones ofrecen enfoques convenientes para operaciones comunes como encontrar un elemento de un array que cumpla con ciertos criterios (verificados a través de una función de callback) y verificar si alguno o todos los elementos del array cumplen con ciertos criterios.

Nuevas funciones de PHP 8.4 para encontrar elementos de un array mediante una función de callback:

  • array_find: Devuelve el valor del primer elemento del array para el cual el callback devuelve true; de lo contrario, devuelve null.
  • array_find_key: Devuelve la clave del primer elemento del array para el cual el callback devuelve true; de lo contrario, devuelve null.

Nuevas funciones de PHP 8.4 para verificar si alguno o todos los elementos pasan una verificación con un callback:

  • array_all: Verifica si el callback devuelve true para todos los elementos del array.
  • array_any: Verifica si el callback devuelve true para alguno de los elementos del array.

Nueva función array_find

La función array_find devuelve el valor del primer elemento del array para el cual el callback devuelve true. Si ninguno de los elementos cumple con la condición, la función array_find devuelve null. Sinopsis de la función:

/**
 * Devuelve el VALOR del primer elemento del array ($array) para el cual el
 * callback ($callback) devuelve true. Devuelve NULL si no se encuentra
 * ningún elemento que cumpla con la condición.
 *
 * @param array $array El array que se debe buscar.
 * @param callable $callback La función de callback que se llamará para
 * verificar cada elemento. El primer parámetro contiene el valor ($value),
 * el segundo parámetro contiene la clave correspondiente ($key). Si este
 * callback devuelve TRUE (o un valor verdadero), el valor ($value) se
 * devuelve inmediatamente y el callback no se llamará para más elementos.
 *
 * @return mixed La función devuelve el valor del primer elemento para el
 * cual el callback devuelve TRUE. NULL si no se encuentra ningún elemento
 * que cumpla con la condición. Tenga en cuenta que el valor del elemento
 * que coincide también podría ser NULL.
 */
function array_find(array $array, callable $callback): mixed {}

Ejemplos de uso de 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"

Nueva función array_find_key

La función array_find_key es similar a la función array_find, pero devuelve la clave del primer elemento del array para el cual el callback devuelve true. Si ninguno de los elementos cumple con la condición, la función array_find_key devuelve null. 

Sinopsis de la función:

/**
 * Devuelve la CLAVE del primer elemento del array ($array) para el cual el
 * callback ($callback) devuelve TRUE. Si no se encuentra ningún elemento que
 * cumpla con la condición, la función devuelve NULL.
 *
 * @param array $array El array que se debe buscar.
 * @param callable $callback La función de callback que se llamará para
 * verificar cada elemento. El primer parámetro contiene el valor ($value),
 * el segundo parámetro contiene la clave correspondiente ($key). Si esta
 * función devuelve TRUE, la clave ($key) se devuelve inmediatamente y el
 * callback no se llamará para más elementos.
 *
 * @return mixed La clave del primer elemento para el cual el callback
 * devuelve TRUE. NULL si no se encuentra ningún elemento que cumpla con la
 * condición.
 */
function array_find_key(array $array, callable $callback): mixed {}

Ejemplos de uso de 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"

Nueva función array_all

La función array_all toma un array y un callback, y devuelve true si todos los elementos del array devuelven true cuando se les pasa al callback.

La función de callback se llama con el valor ($value) y la clave ($key) de cada elemento del array dado.

array_all devuelve true en arrays vacíos ([]). 

Sinopsis de la función:

/**
 * Verifica si el callback ($callback) devuelve TRUE para TODOS los
 * elementos del array.
 *
 * @param array $array El array que se debe buscar.
 * @param callable $callback La función de callback que se llamará para
 * verificar cada elemento. El primer parámetro contiene el valor ($value),
 * el segundo parámetro contiene la clave correspondiente. Si esta función
 * devuelve FALSE (o cualquier valor falso), se devuelve FALSE
 * inmediatamente y el callback no se llamará para más elementos.
 *
 * @return bool TRUE, si el callback devuelve TRUE para todos los elementos.
 * FALSE en caso contrario.
 */
function array_all(array $array, callable $callback): bool {}

Ejemplos de uso de 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

Nueva función array_any

La función array_any es similar a la función array_all. Toma un array y un callback, y devuelve true si alguno de los elementos del array devuelve true cuando se le pasa al callback.

La función de callback se llama con el valor ($value) y la clave ($key) de cada elemento del array dado. Una vez que el primer elemento devuelve true en el callback, la función no se llama en el resto de los elementos del array.

array_any devuelve false en arrays vacíos ([]). 

Sinopsis de la función:

/**
 * Verifica si el callback ($callback) devuelve TRUE para ALGUNO de los
 * elementos del array.
 *
 * @param array $array El array que se debe buscar.
 * @param callable $callback La función de callback que se llamará para
 * verificar cada elemento. El primer parámetro contiene el valor ($value),
 * el segundo parámetro contiene la clave correspondiente ($key). Si esta
 * función devuelve TRUE (o un valor verdadero), se devuelve TRUE
 * inmediatamente y el callback no se llamará para más elementos.
 *
 * @return bool TRUE si hay al menos un elemento para el cual el callback
 * devuelve TRUE. FALSE en caso contrario.
 */
function array_any(array $array, callable $callback): bool {}

Ejemplos de uso de array_any:

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

array_any(
    ['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

Impacto en la compatibilidad retroactiva

Las funciones array_find, array_find_key, array_all, y array_any son nuevas funciones agregadas al espacio de nombres global. A menos que existan funciones de usuario con los mismos nombres, este cambio no debería introducir problemas de compatibilidad retroactiva.

Las nuevas funciones también pueden ser implementadas fácilmente en el código del usuario en PHP.

El paquete polyfills/array_find proporciona un polyfill de PHP para las funciones array_find, array_find_key, array_all, y array_any, compatible con PHP 7.1 y versiones posteriores.

El siguiente comando de Composer lo instala:

composer require polyfills/array-find