filter_var()

Purpose

filter_var() checks or cleans a single value using a named filter. Most often you use it with a FILTER_VALIDATE_* constant to decide whether input looks like an integer, a boolean, an email address, a URL and so on. It can also apply a FILTER_SANITIZE_* filter or a custom FILTER_CALLBACK. It is a compact alternative to hand-written regular expressions for common formats.

Signature

Parameters and defaults

• $value: the value to filter. Scalar values are converted to a string internally before filtering, so true is seen as "1" and false as an empty string. Arrays are only processed when you pass FILTER_REQUIRE_ARRAY or FILTER_FORCE_ARRAY as a flag.
• $filter: which filter to run. The default is FILTER_DEFAULT, an alias of FILTER_UNSAFE_RAW, which means that no filtering happens at all. Always pass a filter explicitly when you want validation.
• $options: either a bitmask of FILTER_FLAG_* constants, or an associative array. Inside the array, the "options" key holds filter-specific settings such as min_range, max_range or default, and the "flags" key holds the flags. The default is 0, meaning no flags and no options.

Return value and failure

On success the function returns the filtered data. Validation filters return the value converted to the natural type, for example an int for FILTER_VALIDATE_INT. On failure it returns false. If you pass FILTER_NULL_ON_FAILURE, failure returns null instead. If you supply a default entry in the "options" array, that default is returned when validation fails.

The function does not throw an exception for invalid input. Failure is reported only through the return value, so you must check it carefully.

Example 1: validating integers

Integer validation accepts optional surrounding whitespace, but rejects decimals, text and numbers with leading zeros. Use a strict comparison with false, because 0 is a valid integer result.

<?php
$inputs = ['42', ' 42 ', '4.2', 'abc', '007'];
$result = [];
foreach ($inputs as $input) {
    $result[] = filter_var($input, FILTER_VALIDATE_INT);
}
echo json_encode($result), "\n";

[42,42,false,false,false]

Example 2: range checks and defaults

The nested "options" array lets you restrict a number to a range. Adding default replaces a failure with a fallback value, which is handy for page numbers or limits.

<?php
$options = ['options' => ['min_range' => 1, 'max_range' => 100, 'default' => 10]];
$values = ['50', '500', 'x'];
$out = [];
foreach ($values as $value) {
    $out[] = filter_var($value, FILTER_VALIDATE_INT, $options);
}
echo json_encode($out), "\n";

[50,10,10]

Example 3: booleans and FILTER_NULL_ON_FAILURE

With FILTER_VALIDATE_BOOLEAN, plain false is ambiguous: it can mean the input was a valid false value, or it can mean the input was invalid. The FILTER_NULL_ON_FAILURE flag separates the two cases.

<?php
$values = ['yes', 'off', '0', 'maybe', ''];
$out = [];
foreach ($values as $value) {
    $out[] = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
}
echo json_encode($out), "\n";

[true,false,false,null,false]

Edge cases

• Because scalars are turned into strings first, the filter judges the string form, not the original PHP type.
• FILTER_VALIDATE_BOOLEAN treats an empty string as false, even with FILTER_NULL_ON_FAILURE. Only genuinely unrecognized text becomes null.
• Flags can be passed directly as the third argument, or inside the array under "flags". Use the array form whenever you also need "options".
• To validate every element of an array, pass FILTER_REQUIRE_ARRAY. Each entry is then filtered and you receive an array with the filtered value or a failure marker for each key.
• FILTER_VALIDATE_EMAIL and FILTER_VALIDATE_URL check format only. They cannot tell you whether a mailbox or a web page actually exists, and an address on an unusual domain such as .local can still pass.

Common mistakes

1. Relying on the default filter. filter_var($x) returns the value as a string and checks nothing.
2. Using a loose truth test. if (filter_var($n, FILTER_VALIDATE_INT)) rejects a valid 0. Compare with false using ===, or use FILTER_NULL_ON_FAILURE where it applies.
3. Confusing sanitizing with validating. A sanitize filter strips characters and still returns a string. It does not tell you whether the original input was acceptable.
4. Expecting security from validation alone. A valid email string still needs escaping or parameter binding when it is printed in HTML or used in a query.
5. Forgetting the nested array. Settings such as min_range must be placed under the "options" key, not at the top level of the third argument.

Related functions

• filter_var_array() filters several values at once and can apply a different filter to each key.
• filter_input() reads an external variable such as request data by name and optionally filters it.
• filter_input_array() does the same for a group of external variables.

Recap

filter_var() applies one filter to one value and returns the filtered result, false on failure, or null when FILTER_NULL_ON_FAILURE is set. Choose the filter explicitly, put filter settings under "options", put flags under "flags", and compare results strictly so that valid values such as 0 or false are not mistaken for errors.