filter_input_array

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

filter_input_array — Obtiene variables externas y opcionalmente las filtra

Descripción

function filter_input_array(int $type, array|int $options = FILTER_DEFAULT, bool $add_empty = true): array|false|null

Esta función es útil para recuperar muchos valores sin necesidad de llamar repetidamente a filter_input().

Parámetros

type

Una de las constantes INPUT_*.

Advertencia

El contenido de la superglobal que se está filtrando es el original "sin procesar" proporcionado por SAPI, antes de cualquier modificación del usuario a la superglobal. Para filtrar una superglobal modificada, utilice filter_var_array() en su lugar.

options

Ya sea un array asociativo de opciones, o el filtro que se aplicará a cada entrada, que puede ser un filtro de validación mediante el uso de una de las constantes FILTER_VALIDATE_* o un filtro de saneamiento mediante el uso de una de las constantes FILTER_SANITIZE_*.

La array de opciones es un array asociativo donde la clave corresponde a una clave del array de entrada y el valor asociado es el filtro a aplicar a esta entrada, o un array asociativo que describe cómo y qué filtro se debe aplicar a esta entrada.

El array asociativo que describe cómo se debe aplicar un filtro debe contener la clave 'filter' cuyo valor asociado es el filtro a aplicar, que puede ser uno de las constantes FILTER_VALIDATE_*, FILTER_SANITIZE_*, FILTER_UNSAFE_RAW, o FILTER_CALLBACK. Opcionalmente, puede contener la clave 'flags', que especifica cualquier flag que se aplique al filtro, y la clave 'options', que especifica las opciones que se aplican al filtro.

add_empty

Añade claves faltantes como null al valor devuelto.

Valores devueltos

En caso de éxito, un array que contiene los valores de las variables solicitadas.

En caso de fallo, se devuelve false. Si el array de entrada designado por type no está poblado, se devuelve null en su lugar.

Las entradas faltantes del array de entrada se añaden al array devuelto como null si add_empty es true, y se omiten por completo si es false. A diferencia de filter_input(), el flag FILTER_NULL_ON_FAILURE no cambia esto: una entrada faltante siempre es null.

Un valor del array devuelto será false si el filtro falla, a menos que se use el flag FILTER_NULL_ON_FAILURE, en cuyo caso será null. Con el flag FILTER_FORCE_ARRAY, ese valor de fallo se envuelve en un array de un solo elemento como cualquier otro resultado.

Ejemplos

Ejemplo #1 Ejemplo de filter_input_array()

Este ejemplo supone una petición GET a ?email=user@example.com&age=twenty&url=https://example.com. La entrada age falla porque twenty no es un entero; un valor fuera del rango de 1 a 120 fallaría de la misma manera.

<?php
$filters = [
    'email' => FILTER_VALIDATE_EMAIL,
    'age'   => [
        'filter'  => FILTER_VALIDATE_INT,
        'options' => ['min_range' => 1, 'max_range' => 120],
    ],
    'url'   => FILTER_VALIDATE_URL,
];

$result = filter_input_array(INPUT_GET, $filters);

var_dump($result);
?>

Resultado del ejemplo anterior es similar a:

array(3) {
  ["email"]=>
  string(16) "user@example.com"
  ["age"]=>
  bool(false)
  ["url"]=>
  string(19) "https://example.com"
}

Ejemplo #2 Filtrado de datos POST con filter_input_array()

Este ejemplo supone una petición POST con los campos username=<script>alert</script> y comment=Hello World. No se envía ningún campo missing: como add_empty vale true por defecto, sigue estando presente en el resultado, establecido a null.

<?php
$filters = [
    'username' => FILTER_SANITIZE_SPECIAL_CHARS,
    'comment'  => FILTER_SANITIZE_SPECIAL_CHARS,
    'missing'  => FILTER_VALIDATE_INT,
];

$result = filter_input_array(INPUT_POST, $filters);

var_dump($result);
?>

Resultado del ejemplo anterior es similar a:

array(3) {
  ["username"]=>
  string(38) "&#60;script&#62;alert&#60;/script&#62;"
  ["comment"]=>
  string(11) "Hello World"
  ["missing"]=>
  NULL
}

Ejemplo #3 Petición de un tipo de entrada que no está poblado

Este ejemplo supone una petición GET. Como la petición no llevaba ningún campo POST, el array de entrada designado por INPUT_POST no está poblado y se devuelve null en lugar de un array. Esto se aplica a todos los tipos de entrada: una petición sin cadena de consulta devuelve también null para INPUT_GET.

<?php
var_dump(filter_input_array(INPUT_POST, ['a' => FILTER_VALIDATE_INT]));
?>

Resultado del ejemplo anterior es similar a:

NULL

Notas

Nota:
No hay una clave REQUEST_TIME en el array INPUT_SERVER porque este valor es insertado en $_SERVER posteriormente.

Véase también

filter_input() - Toma una variable externa concreta por su nombre y opcionalmente la filtra
filter_var() - Filtra una variable con el filtro que se indique
filter_var_array() - Obtiene múltiple variables y opcionalmente las filtra
Filtros de validación FILTER_VALIDATE_*
Filtros de saneación FILTER_SANITIZE_*