filter_input

Reads one variable from GET, POST, COOKIE, SERVER or ENV and validates or sanitizes it in one step.

Signature

filter_input(int $type, string $var_name, int $filter = FILTER_DEFAULT, array|int $options = 0): mixed

Added in PHP 5.2.0

Parameters

Parameter	Type	Description
`$type`	`int`	One of INPUT_GET, INPUT_POST, INPUT_COOKIE, INPUT_SERVER or INPUT_ENV.
`$var_name`	`string`	Name of the variable to read from that input type.
`$filter`optional	`int`= `FILTER_DEFAULT`	The filter to apply: a FILTER_VALIDATE_, FILTER_SANITIZE_, FILTER_UNSAFE_RAW or FILTER_CALLBACK constant.
`$options`optional	`array\|int`= `0`	An associative array with 'flags' and 'options' keys, or a bitmask of FILTER_FLAG_* constants.

Return value

mixedThe filtered value, false if filtering fails, or null if the variable was not set. With FILTER_NULL_ON_FAILURE the meanings swap: false means not set, null means the filter failed.

Errors

Throws a ValueError for an invalid input type ("filter_input(): 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: it raises an "Unknown filter with ID %d" warning and returns false. 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 returning 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, and the always-implied FILTER_FLAG_SCHEME_REQUIRED and FILTER_FLAG_HOST_REQUIRED flags were removed.

Example

<?php
// Assume the browser requested: /search.php?q=%3Cb%3Ephp%3C%2Fb%3E&page=3&limit=abc

$q     = filter_input(INPUT_GET, 'q', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
$page  = filter_input(INPUT_GET, 'page', FILTER_VALIDATE_INT, ['options' => ['min_range' => 1]]);
$limit = filter_input(INPUT_GET, 'limit', FILTER_VALIDATE_INT);
$sort  = filter_input(INPUT_GET, 'sort', FILTER_VALIDATE_INT);

var_dump($q);     // string: &lt;b&gt;php&lt;/b&gt;
var_dump($page);  // int(3)
var_dump($limit); // bool(false) — sent, but not an integer
var_dump($sort);  // NULL — never sent

When to use it

Read a ?page= query parameter as an integer with a minimum of 1, rejecting "abc" and negative numbers.
Validate a signup form's email field straight out of the POST body before touching the database.
Cast a "remember me" cookie to a boolean without trusting whatever string the browser sent.

Frequently asked questions

What is the difference between filter_input and filter_var?

filter_input reads from the raw request data the SAPI gave PHP, so it ignores changes made to $_GET or $_POST; filter_var filters any value you hand it. Use filter_var when the value already lives in a variable, or when you need the code to be testable on the CLI.

Does the 'default' option apply when the variable was never sent?

It does not — filter_input() returns the 'default' option for a missing variable as well as for one that fails the filter, so filter_input(INPUT_GET, 'missing', FILTER_VALIDATE_INT, ['options' => ['default' => 1]]) gives int(1). You only get null for a missing key when no 'default' option is given. (filter_input_array() is the one that ignores 'default' for missing keys and always yields null there.)

Does filter_input sanitize by default?

No. The filter parameter defaults to FILTER_DEFAULT, an alias of FILTER_UNSAFE_RAW, which returns the value untouched. You must pass an explicit FILTER_VALIDATE_* or FILTER_SANITIZE_* constant.

More examples

Telling "not sent" from "invalid"

With <code>?id=abc</code> this prints the "sent but is not a whole number" branch. Drop the parameter entirely and the same code prints "No id in the request" — one call covers both checks, which is why a loose <code>if (!$id)</code> would be wrong here.

<?php
// GET /item.php?id=abc

$id = filter_input(INPUT_GET, 'id', FILTER_VALIDATE_INT);

if ($id === null) {
    echo "No id in the request\n";
} elseif ($id === false) {
    echo "id was sent but is not a whole number\n";
} else {
    echo "Loading item $id\n";
}

Booleans and defaults done properly

FILTER_VALIDATE_BOOL accepts 1, true, on and yes as true, and 0, false, off, no and "" as false. With FILTER_NULL_ON_FAILURE anything else becomes null, so the <code>?? false</code> covers both a garbage cookie and a missing one — the ordinary return value <code>false</code> is no longer ambiguous.

<?php
// COOKIE: remember=yes

$remember = filter_input(
    INPUT_COOKIE,
    'remember',
    FILTER_VALIDATE_BOOL,
    FILTER_NULL_ON_FAILURE
) ?? false;

var_dump($remember); // bool(true)

Discussion

Be the first to comment on this lesson.