Как пользоваться filter_var в PHP
Функция filter_var проверяет значения из форм, JSON и настроек и возвращает результат, который можно передать дальше в приложение. Разберём, что возвращают разные фильтры, как задавать флаги и диапазоны и где нужна отдельная проверка.
Как работает filter_var
В PHP 8.3–8.5 у filter_var() три аргумента: значение, идентификатор фильтра и необязательные настройки. Для одиночного флага передайте целое число третьим аргументом. Если фильтру нужны параметры, передайте массив с ключом options. В том же массиве можно указать ключ flags.
Возвращаемое значение зависит от фильтра. Например, FILTER_VALIDATE_INT возвращает int, а FILTER_VALIDATE_EMAIL при успехе возвращает строку. Большинство фильтров валидации сигнализируют об ошибке через false. Всегда проверяйте такой результат строгим сравнением === false, иначе успешный результат 0 может попасть в ветку ошибки. Вызов filter_var($value) применяет FILTER_DEFAULT, псевдоним FILTER_UNSAFE_RAW. Для проверки формата указывайте фильтр явно.
Функция преобразует скалярные значения в строки перед фильтрацией. Директива declare(strict_types=1) полезна для типизированного кода приложения, но аргумент filter_var() имеет тип mixed, поэтому поведение фильтра сохраняется. Например, проверка true через FILTER_VALIDATE_INT вернёт 1. Если по контракту поле должно быть строкой или целым числом, проверьте его тип на входе.
Целые и дробные числа
Для целого числа используйте FILTER_VALIDATE_INT. Параметры min_range и max_range включают границы. В примере входное значение пришло из формы, а диапазон допускает нулевое смещение. Тип поля проверяется отдельно: клиент может отправить массив вместо строки.
<?php
declare(strict_types=1);
$raw = $_POST['offset'] ?? null;
if (!is_string($raw)) {
throw new InvalidArgumentException('Укажите смещение одной строкой');
}
$offset = filter_var($raw, FILTER_VALIDATE_INT, [
'options' => ['min_range' => 0, 'max_range' => 10_000],
]);
if ($offset === false) {
throw new InvalidArgumentException('Смещение должно быть целым от 0 до 10000');
}
// Здесь $offset имеет тип int и может быть равен 0.Строка 007 не проходит обычную проверку FILTER_VALIDATE_INT. Если ведущие нули значимы, например в коде товара, храните значение строкой и проверяйте допустимые символы и длину. Флаги FILTER_FLAG_ALLOW_OCTAL и FILTER_FLAG_ALLOW_HEX включайте для полей, где эти системы счисления предусмотрены форматом. Передавайте строку, если важно проверить именно её запись: числовой литерал PHP уже разобран к моменту вызова функции.
Для дробных значений используйте FILTER_VALIDATE_FLOAT. Параметр decimal задаёт десятичный разделитель. Если интерфейс принимает числа с запятой, укажите её явно. Согласуйте формат с клиентом, поскольку запись 1,234 может обозначать и дробь, и целое число с разделителем тысяч. Для денежных расчётов используйте целые суммы в минимальных единицах валюты или десятичную арифметику: двоичный float округляет многие десятичные дроби.
<?php
// Десятичный разделитель задан форматом поля.
$weight = filter_var('1,25', FILTER_VALIDATE_FLOAT, [
'options' => ['decimal' => ','],
]);
var_dump($weight); // float(1.25)Булевы значения: как отличить false от ошибки
FILTER_VALIDATE_BOOL и FILTER_VALIDATE_BOOLEAN обозначают один фильтр. Он распознаёт 1, true, on и yes как истину, а 0, false, off, no и пустую строку как ложь. Регистр букв в этих строках не важен. Укажите FILTER_NULL_ON_FAILURE, чтобы получить null для неизвестного значения и сохранить false для корректной лжи.
<?php
// Флаг позволяет различить ложь и неизвестное значение.
$flags = FILTER_NULL_ON_FAILURE;
var_dump(filter_var('off', FILTER_VALIDATE_BOOL, $flags)); // bool(false)
var_dump(filter_var('yes', FILTER_VALIDATE_BOOL, $flags)); // bool(true)
var_dump(filter_var('maybe', FILTER_VALIDATE_BOOL, $flags)); // NULLПроверяйте наличие поля до фильтрации, если отсутствие и ложь имеют разный смысл. HTML-форма обычно не отправляет выключенный чекбокс, поэтому для него отсутствие поля может означать false. В запросе на частичное обновление отсутствие поля может означать, что настройку следует оставить как есть. Для JSON с обязательным булевым типом достаточно is_bool() после разбора тела запроса. Если нужно различить отсутствующий ключ и явно переданный null, используйте array_key_exists().
Электронная почта
FILTER_VALIDATE_EMAIL проверяет синтаксис адреса. Существование почтового ящика и доступ пользователя к нему подтверждаются письмом с одноразовым кодом или ссылкой. Пробелы вокруг адреса из формы можно удалить перед проверкой, если приложение считает их случайным вводом.
<?php
$raw = $_POST['email'] ?? null;
if (!is_string($raw)) {
throw new InvalidArgumentException('Укажите один email');
}
// Убираем пробелы по краям адреса из формы.
$email = filter_var(trim($raw), FILTER_VALIDATE_EMAIL);
if ($email === false) {
throw new InvalidArgumentException('Проверьте формат email');
}Если продукт принимает международные адреса, обрабатывайте доменную часть и часть до символа @ по отдельности. Для Unicode в локальной части предусмотрен FILTER_FLAG_EMAIL_UNICODE. Интернациональное имя домена для проверки преобразуйте в ASCII через idn_to_ascii() из расширения intl и обработайте возможную ошибку преобразования. Для доставки на адрес с Unicode в локальной части нужна поддержка SMTPUTF8 со стороны почтовой инфраструктуры.
URL и IP-адреса
Проверка схемы URL
FILTER_VALIDATE_URL проверяет синтаксис и допускает разные схемы. Если поле предназначено для веб-ссылок, проверьте схему через parse_url() и список разрешённых значений. Следующая функция принимает только HTTPS. Флаги FILTER_FLAG_PATH_REQUIRED и FILTER_FLAG_QUERY_REQUIRED пригодятся, когда формат поля требует наличия пути или строки запроса.
<?php
declare(strict_types=1);
function isHttpsLink(mixed $value): bool
{
if (!is_string($value) || filter_var($value, FILTER_VALIDATE_URL) === false) {
return false;
}
// Разрешаем только схему HTTPS без учёта регистра.
$scheme = parse_url($value, PHP_URL_SCHEME);
return is_string($scheme) && strtolower($scheme) === 'https';
}Фильтр URL рассчитан на ASCII. Для международных имён преобразуйте хост в ASCII, а компоненты пути и запроса кодируйте по правилам URL. Если приложение само загружает ресурс по пользовательскому адресу, проверка формата и схемы покрывает лишь входное поле. Защита от SSRF требует правил для фактических сетевых назначений с учётом DNS и перенаправлений.
Проверка IP и диапазона
FILTER_VALIDATE_IP принимает IPv4 и IPv6. Чтобы разрешить одно семейство, задайте FILTER_FLAG_IPV4 или FILTER_FLAG_IPV6. Для требования глобального диапазона есть FILTER_FLAG_GLOBAL_RANGE. Если нужно исключить конкретные категории адресов, доступны FILTER_FLAG_NO_PRIV_RANGE и FILTER_FLAG_NO_RES_RANGE. Флаг диапазона проверяет классификацию адреса. Доступность узла проверяется отдельно.
<?php
// Проверяем, что адрес принадлежит глобальному диапазону IPv4.
$flags = FILTER_FLAG_IPV4 | FILTER_FLAG_GLOBAL_RANGE;
var_dump(filter_var('10.0.0.1', FILTER_VALIDATE_IP, $flags)); // bool(false)Собственные форматы и очистка данных
Для проектного формата можно использовать FILTER_VALIDATE_REGEXP с параметром regexp. При совпадении фильтр вернёт строку, а при несовпадении — false. Для проверки всего поля ограничьте выражение через \A и \z. Если нужны группы совпадений, используйте preg_match() напрямую.
<?php
// Артикул состоит из трёх заглавных букв и четырёх цифр.
$sku = filter_var('ABC-0042', FILTER_VALIDATE_REGEXP, [
'options' => ['regexp' => '/\A[A-Z]{3}-[0-9]{4}\z/'],
]);
var_dump($sku); // string(8) "ABC-0042"Очищающие фильтры меняют входное значение. Например, FILTER_SANITIZE_NUMBER_INT превратит 12kg в 12 и сохранит знаки плюса и минуса, где бы они ни стояли. Для поля с целым числом применяйте FILTER_VALIDATE_INT к исходному значению, чтобы ошибочный ввод дошёл до сообщения об ошибке. Нормализуйте только то, что явно допускает формат поля.
Валидация и безопасное использование значения выполняются на разных этапах. При выводе строки в HTML используйте htmlspecialchars() с ENT_QUOTES | ENT_SUBSTITUTE и кодировкой UTF-8. При передаче значения в SQL используйте параметры подготовленного запроса. Эти операции нужны и для данных, успешно прошедших проверку формата.
Чек-лист для проверки входных данных
- Определите тип поля и смысл отсутствующего ключа, пустой строки и
null. Проверьте форму данных до вызова фильтра. - Укажите
FILTER_VALIDATE_*явно. Задайте диапазон, схему, семейство адресов или шаблон по контракту поля. - Сравнивайте результат через
=== false. Для булевых строк добавьтеFILTER_NULL_ON_FAILUREи проверяйте=== null. - После проверки формата примените правила приложения. Например, подтвердите владение почтой и проверьте права на изменение записи.
- Передайте дальше проверенное значение нужного типа. Экранируйте вывод и передавайте параметры в запросы по правилам конкретного контекста.
Частые вопросы
Почему filter_var возвращает false для корректного значения?
У булева фильтра false означает и успешно распознанную ложь, и ошибку разбора. С флагом FILTER_NULL_ON_FAILURE ошибка возвращается как null, а корректная ложь остаётся false.
Чем filter_var отличается от filter_input?
filter_var проверяет значение, которое вы передали ему из любого источника. filter_input читает конкретную переменную из поддерживаемого источника PHP, например INPUT_GET или INPUT_POST, и работает с исходным значением запроса до изменений соответствующего суперглобального массива.
Можно ли передать несколько флагов одновременно?
Да. Объедините совместимые флаги оператором | и передайте результат третьим аргументом или в ключе flags, если одновременно задаёте параметры в options. У каждого фильтра свой набор поддерживаемых флагов.