filter_input_array

Reads and filters many request variables at once from GET, POST, COOKIE, SERVER or ENV.

Signature
filter_input_array(int $type, array|int $options = FILTER_DEFAULT, bool $add_empty = true): array|false|null
  • Added in PHP 5.2.0

Parameters

ParameterTypeDescription
$typeintOne of INPUT_GET, INPUT_POST, INPUT_COOKIE, INPUT_SERVER or INPUT_ENV.
$optionsoptionalarray|int= FILTER_DEFAULTEither a single filter constant applied to every entry, or an array mapping each key to a filter constant or to an array with 'filter', 'flags' and 'options' keys.
$add_emptyoptionalbool= trueWhen true, keys named in options but missing from the input are added to the result as null; when false they are omitted.

Return value

array|false|nullAn array of filtered values on success, false on failure, or null if the requested input type is not populated. Individual entries are false when their filter fails.

Errors

Throws a ValueError for an invalid input type ("Argument #1 ($type) must be an INPUT_* constant"), and for incompatible flag combinations such as FILTER_NULL_ON_FAILURE together with FILTER_THROW_ON_FAILURE. An unknown filter ID does not throw a ValueError — the entry is simply left unfiltered (or, when a bare unknown ID is passed as the whole options argument, a warning is raised and false is returned). In PHP 8.5, a validation failure throws Filter\FilterFailedException when FILTER_THROW_ON_FAILURE is set.

Changelog

  • PHP 8.5The FILTER_THROW_ON_FAILURE flag was added; a failing validation filter throws Filter\FilterFailedException instead of yielding false. It cannot be combined with FILTER_NULL_ON_FAILURE.
  • PHP 8.1FILTER_SANITIZE_STRING and its alias FILTER_SANITIZE_STRIPPED are deprecated; use htmlspecialchars() instead.
  • PHP 8.0INPUT_REQUEST and INPUT_SESSION were removed, so those input types can no longer be passed.

See also

filter_inputfilter_var_arrayfilter_varfilter_has_var

filter_input_array() is filter_input() applied to a whole request at once. You describe the shape of the expected input as an array of rules, and you get back an array with the same keys, already validated or sanitized. Like filter_input() it reads the raw SAPI data, not the live superglobal.

When to reach for it

Use it as the front door of a form handler. One declarative $filters array documents every field the endpoint accepts, and anything not listed simply does not appear in the result — which is a whitelist for free. It also removes the temptation to loop over $_POST and trust whatever keys turn up.

What trips people up

The return value has three shapes, and confusing them is the usual bug. If the entire input type is empty — a GET request has no POST body — you get null, not an array of nulls, so $in['email'] fatals on null. Check the return with if (!is_array($in)) first.

Inside the array, a field that failed validation is false, while a field that was never sent is null (or absent, when add_empty is false). Test with ===; a loose truthiness check treats a legitimate 0 as a failure.

Example

Example · php
<?php
// POST body: [email protected]&age=30&nick=<b>bob</b>

$filters = [
    'email' => FILTER_VALIDATE_EMAIL,
    'age'   => ['filter' => FILTER_VALIDATE_INT,
                'options' => ['min_range' => 13, 'max_range' => 120]],
    'nick'  => FILTER_SANITIZE_FULL_SPECIAL_CHARS,
    'phone' => FILTER_VALIDATE_INT,
];

$input = filter_input_array(INPUT_POST, $filters);

if (!is_array($input)) {
    echo "Nothing was POSTed\n";
} else {
    print_r($input);
}
// [email] => [email protected]  [age] => 30
// [nick] => &lt;b&gt;bob&lt;/b&gt;  [phone] => (null, never sent)

When to use it

  • Validate an entire registration form (email, age, username) in one call at the top of a POST handler.
  • Whitelist which query-string parameters an API endpoint accepts and reject everything else by omission.
  • Pull a set of tracking cookies, casting each to the right type, before writing them to a session.

Frequently asked questions

What is the difference between filter_input_array and filter_var_array?

filter_input_array reads the raw request data for a given INPUT_* type, so it ignores any changes made to the superglobals; filter_var_array filters an array you pass in yourself. Use filter_var_array when the data is already in a variable or when you need the code to run under the CLI.

Why does filter_input_array return null?

It returns null when the whole input type is unpopulated — for example asking for INPUT_POST during a GET request, or any input type on the CLI. Guard with is_array() before indexing the result.

How do I tell which field failed validation?

Compare each entry with === false; a failed filter yields false, a key that was never sent yields null when add_empty is true. Do not use a truthiness check, because a valid integer 0 or an empty string is also falsy.

More examples

Separating missing fields from invalid ones

Both submitted fields fail their filters and come back as <code>false</code>, while <code>city</code> was never sent and comes back as <code>null</code> thanks to the default <code>add_empty</code>. Strict comparison is what keeps the two apart — and what stops a valid <code>0</code> being reported as invalid.

Example · php
<?php
// POST body: email=nope&age=200

$filters = ['email' => FILTER_VALIDATE_EMAIL,
            'age'   => ['filter' => FILTER_VALIDATE_INT,
                        'options' => ['max_range' => 120]],
            'city'  => FILTER_SANITIZE_FULL_SPECIAL_CHARS];

$in = filter_input_array(INPUT_POST, $filters) ?: [];

foreach ($filters as $field => $_) {
    $v = $in[$field] ?? null;
    echo $field, ': ', $v === false ? 'invalid' : ($v === null ? 'missing' : $v), "\n";
}
// email: invalid   age: invalid   city: missing

Dropping missing keys and handling multi-value fields

<code>FILTER_REQUIRE_ARRAY</code> tells the filter that <code>tags</code> must arrive as an array and filters each element; without it an array value would come back as <code>false</code>. Passing <code>false</code> for <code>add_empty</code> drops the unsent <code>note</code> key entirely instead of setting it to null.

Example · php
<?php
// POST body: tags[]=php&tags[]=web&id=7

$filters = [
    'tags' => ['filter' => FILTER_SANITIZE_FULL_SPECIAL_CHARS,
               'flags'  => FILTER_REQUIRE_ARRAY],
    'id'   => FILTER_VALIDATE_INT,
    'note' => FILTER_SANITIZE_FULL_SPECIAL_CHARS,
];

print_r(filter_input_array(INPUT_POST, $filters, false));
// [tags] => Array([0] => php [1] => web)  [id] => 7

Related

filter_inputfilter_var_arrayfilter_varfilter_has_vararray_filter

Discussion

  • Be the first to comment on this lesson.