filter_var_array()

Purpose

filter_var_array() runs the filter machinery over an associative array in a single call. It is like calling filter_var() once for every field, but you describe all the rules in one place. It is useful when you already have an array of in-memory data, such as a decoded payload or a prepared form array, and want one result array with cleaned values.

Each entry can be checked with a FILTER_VALIDATE_* filter, changed with a FILTER_SANITIZE_* filter, left raw with FILTER_UNSAFE_RAW, or processed by your own function with FILTER_CALLBACK.

Signature

Parameters and defaults

• $array: the associative array containing the data to filter.
• $options: either one filter constant or an array of rules. The default is FILTER_DEFAULT. When it is an integer, that filter is applied to every entry. When it is an array, each key names an entry in the input and each value is either a filter constant or a description array.
• $add_empty: defaults to true. Keys named in $options but absent from the input appear in the result as null. With false they are left out.

A description array must contain a 'filter' key. It may also contain 'flags' and 'options'. For example, FILTER_VALIDATE_INT accepts min_range and max_range inside 'options'. For FILTER_CALLBACK, the 'options' value is the callable.

Return value and failure cases

On success you get an array of the filtered values. The manual also documents false as the failure return for the whole call.

Failure of an individual entry is reported inside the array. A failed entry is false, unless you add FILTER_NULL_ON_FAILURE to its flags, in which case it is null. Because null is also used for missing keys, it is worth keeping the two cases in mind when you read results.

Entries are treated as scalars unless you use FILTER_REQUIRE_ARRAY or FILTER_FORCE_ARRAY. With FILTER_FORCE_ARRAY, the result for that entry is wrapped in a one-element array, including a failure value.

Example 1: per-field rules

This example validates an integer with a range, an email address and a boolean. It also names a key that does not exist in the input.

<?php
$data = [
    'age' => '42',
    'email' => 'ada@example.com',
    'active' => 'yes',
];
$filters = [
    'age' => ['filter' => FILTER_VALIDATE_INT, 'options' => ['min_range' => 1, 'max_range' => 120]],
    'email' => FILTER_VALIDATE_EMAIL,
    'active' => FILTER_VALIDATE_BOOLEAN,
    'nickname' => FILTER_DEFAULT,
];
echo json_encode(filter_var_array($data, $filters), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

{"age":42,"email":"ada@example.com","active":true,"nickname":null}

The string '42' becomes the integer 42, 'yes' becomes true, and the absent nickname becomes null.

Example 2: failures and add_empty

Here one value is not an integer, one is out of range with FILTER_NULL_ON_FAILURE, and one key is missing. The call is made twice to compare $add_empty.

<?php
$data = ['age' => 'abc', 'score' => '15', 'limit' => '5'];
$filters = [
    'age' => FILTER_VALIDATE_INT,
    'score' => [
        'filter' => FILTER_VALIDATE_INT,
        'flags' => FILTER_NULL_ON_FAILURE,
        'options' => ['max_range' => 10],
    ],
    'limit' => FILTER_VALIDATE_INT,
    'missing' => FILTER_VALIDATE_INT,
];
$withEmpty = filter_var_array($data, $filters);
$without = filter_var_array($data, $filters, false);
echo json_encode($withEmpty), "\n";
echo json_encode($without), "\n";

{"age":false,"score":null,"limit":5,"missing":null}
{"age":false,"score":null,"limit":5}

The age entry fails as false, while score fails as null because of the flag. Only the first result contains missing.

Example 3: callbacks and one filter for everything

Use FILTER_CALLBACK for custom cleanup. Pass an integer as $options to apply one filter to every entry.

<?php
$names = ['name' => '  ada  ', 'city' => ' london '];
$rules = [
    'name' => ['filter' => FILTER_CALLBACK, 'options' => 'trim'],
    'city' => ['filter' => FILTER_CALLBACK, 'options' => fn($v) => strtoupper(trim($v))],
];
echo json_encode(filter_var_array($names, $rules)), "\n";

$numbers = ['a' => '1', 'b' => 'x', 'c' => '3'];
echo json_encode(filter_var_array($numbers, FILTER_VALIDATE_INT)), "\n";

{"name":"ada","city":"LONDON"}
{"a":1,"b":false,"c":3}

Edge cases

• Keys in the input that are not mentioned in an options array are not part of the result.
• An array value given to a scalar filter fails, so use FILTER_REQUIRE_ARRAY or FILTER_FORCE_ARRAY when a field holds a list.
• Validation filters can return legitimate falsy values, such as 0 or false from FILTER_VALIDATE_BOOLEAN. Do not use a loose truthiness check to detect failure.
• When a single integer filter is used, every entry gets the same treatment, so mixed data may need an options array instead.

Common mistakes

1. Treating false as the only failure signal. Missing keys give null, and FILTER_NULL_ON_FAILURE changes a failure to null.
2. Forgetting that 'options' and 'flags' live inside the per-key description array, not at the top level.
3. Using a sanitizing filter when validation is needed. Sanitizing changes the text, and does not tell you the input was acceptable.
4. Not allowing for missing keys when $add_empty is true, so downstream code receives unexpected null values.
5. Expecting one unsafe field to make the whole call return false. Normally each entry is judged separately.

Related functions

• filter_var() filters one value.
• filter_input_array() filters external input variables as an array.
• filter_input() reads and filters one external variable by name.

Recap

filter_var_array() applies filters to many array entries at once. Pass one filter constant for all entries, or an options array for per-key control. Check each result for false, null and legitimate falsy values, and choose $add_empty depending on whether missing keys should appear.