filter_input_array()

Введение

filter_input_array() фильтрует целый набор внешних данных — все поля запроса $_GET или $_POST — за один вызов, вместо того чтобы извлекать значения из суперглобальных переменных по одному. Вы передаёте ей определение, которое сопоставляет каждое ожидаемое поле с фильтром (проверка или санирование), и она возвращает array очищенных, проверенных по типу значений.

На этой странице рассматриваются синтаксис, то как читать результат (разница между false, null и отсутствующим ключом), как задавать опции и флаги для отдельных полей, а также сравнение filter_input_array() с её «одиночными» и «произвольно-массивными» аналогами.

Для общего понимания модуля фильтров PHP смотрите PHP Filters и PHP Advanced Filters.

Синтаксис

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

Возвращаемое значение:

• Array отфильтрованных значений при успехе.
• false, если $type недопустим.
• null, если запрошенный источник входных данных не содержит никаких данных (и $add_empty равно false).

Важнее всего — читать отдельные записи, а не общее возвращаемое значение:

Самодостаточный пример

filter_input_array() читает из реальных источников INPUT_POST / INPUT_GET, которые существуют только во время веб-запроса. Чтобы продемонстрировать определения фильтров в виде, который можно запустить из командной строки, приведённый ниже фрагмент использует filter_var_array() — она принимает то же самое определение $filters и применяет тот же механизм, поэтому вывод идентичен тому, что выдал бы filter_input_array(INPUT_POST, $filters) для этих данных.

<?php

// In a real request this array would be $_POST.
$input = [
    'name'  => '<b>Jane</b>',
    'age'   => '30',
    'email' => '[email protected]',
];

$filters = [
    'name'  => FILTER_SANITIZE_FULL_SPECIAL_CHARS, // sanitize: escape HTML
    'age'   => FILTER_VALIDATE_INT,                // validate: must be an int
    'email' => FILTER_VALIDATE_EMAIL,              // validate: must be an email
];

$data = filter_var_array($input, $filters);
// In a controller you would write:
// $data = filter_input_array(INPUT_POST, $filters);

print_r($data);

Вывод:

Array
(
    [name] => <b>Jane</b>
    [age] => 30
    [email] => [email protected]
)

Обратите внимание: name было санировано (теги экранированы), тогда как age и email были проверены (возвращены как настоящий int и подтверждённая string). Поле, не указанное в $filters, полностью исключается из результата.

Обработка недопустимых и отсутствующих полей

Поскольку неудачная проверка возвращает false, а отсутствующее поле — null, никогда не считайте каждую запись пригодной к использованию. Проверяйте данные перед тем, как им доверять:

<?php

$input = [
    'age'   => 'not-a-number',
    'email' => 'bad-email',
];

$filters = [
    'age'     => FILTER_VALIDATE_INT,
    'email'   => FILTER_VALIDATE_EMAIL,
    'missing' => FILTER_VALIDATE_INT, // declared, but absent from input
];

$data = filter_var_array($input, $filters);

print_r($data);

Вывод:

Array
(
    [age] =>
    [email] =>
    [missing] =>
)

print_r ничего не показывает после ключей, потому что age и email равны false (недопустимые значения), а missing — null (отсутствует). В реальном коде различайте их явно:

<?php
if ($data['age'] === false) {
    echo "Age is not a valid integer.";
} elseif ($data['age'] === null) {
    echo "Age was not submitted.";
} else {
    echo "Age is {$data['age']}.";
}

Опции и флаги для отдельных полей

Вместо простой константы фильтра поле может быть вложенным array с ключами filter, options и flags — именно здесь функция раскрывает свою мощь. Используйте options для таких вещей, как диапазон целых чисел, и флаг FILTER_REQUIRE_ARRAY, когда поле передаётся как array (например, мультиселект или name="tags[]").

<?php

$input = [
    'age'  => '200',
    'tags' => ['<a>', '<b>'],
];

$args = [
    'age' => [
        'filter'  => FILTER_VALIDATE_INT,
        'options' => ['min_range' => 0, 'max_range' => 120],
    ],
    'tags' => [
        'filter' => FILTER_SANITIZE_FULL_SPECIAL_CHARS,
        'flags'  => FILTER_REQUIRE_ARRAY, // apply the filter to each element
    ],
];

print_r(filter_var_array($input, $args));

Вывод:

Array
(
    [age] =>
    [tags] => Array
        (
            [0] => <a>
            [1] => <b>
        )

)

age равно false, потому что 200 выходит за пределы диапазона 0–120, а каждый элемент tags был санирован по отдельности благодаря FILTER_REQUIRE_ARRAY.

Сравнение со связанными функциями

Используйте filter_input_array(), когда данные находятся в $_GET/$_POST/и т. д.; используйте filter_var_array(), когда array уже хранится в переменной.

Совместимость с версиями PHP

FILTER_SANITIZE_STRING была устаревшей в PHP 8.1 и удалена в PHP 8.2. Для санирования string в современном PHP используйте FILTER_SANITIZE_FULL_SPECIAL_CHARS (как в примерах выше) или для проверки — специализированный фильтр, например FILTER_VALIDATE_EMAIL.

Зачем использовать

• Безопасность. Фильтрация всего запроса в одном месте не даёт непроверенным значениям просочиться в запросы или разметку. Сочетайте с form validation и подготовленными запросами.
• Читаемость. Определение $filters выступает схемой ожидаемых входных данных, отделяя правила проверки от бизнес-логики.
• Последовательность. Каждое поле проходит через одни и те же отработанные механизмы, поэтому вам не нужно вручную писать проверки isset() + is_numeric() для каждого поля.

Смотрите также PHP Superglobals — о том, откуда берутся эти входные данные.

Практика