# Filter Functions

## Introduction

This extension serves to validate and filter data coming from some insecure source, such as user input.

The following filters currently exist; be sure to read the Filter Constants section for information that describes the behavior of each constant:

Existing filters
ID | Name | Options | Flags | Description
--- | --- | --- | --- | ---
`FILTER_VALIDATE_INT` | "int" | `min_range` , `max_range` | `FILTER_FLAG_ALLOW_OCTAL`, `FILTER_FLAG_ALLOW_HEX` | Validates value as integer, optionally from the specified range.
`FILTER_VALIDATE_BOOLEAN` | "boolean" |  | `FILTER_NULL_ON_FAILURE` | Returns `TRUE` for "1", "true", "on" and "yes". Returns `FALSE` otherwise. If `FILTER_NULL_ON_FAILURE` is set, `FALSE` is returned only for "0", "false", "off", "no", and "", and `NULL` is returned for all non-boolean values.
`FILTER_VALIDATE_FLOAT` | "float" | `decimal` | `FILTER_FLAG_ALLOW_THOUSAND` | Validates value as float.
`FILTER_VALIDATE_REGEXP` | "validate_regexp" | `regexp` |  | Validates value against `regexp` , a Perl-compatible regular expression.
`FILTER_VALIDATE_URL` | "validate_url" |  | `FILTER_FLAG_PATH_REQUIRED`, `FILTER_FLAG_QUERY_REQUIRED` | Validates value as URL, optionally with required components.
`FILTER_VALIDATE_EMAIL` | "validate_email" |  |  | Validates value as e-mail.
`FILTER_VALIDATE_IP` | "validate_ip" |  | `FILTER_FLAG_IPV4`, `FILTER_FLAG_IPV6`, `FILTER_FLAG_NO_PRIV_RANGE`, `FILTER_FLAG_NO_RES_RANGE` | Validates value as IP address, optionally only IPv4 or IPv6 or not from private or reserved ranges.
`FILTER_SANITIZE_STRING` | "string" |  | `FILTER_FLAG_NO_ENCODE_QUOTES`, `FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_LOW`, `FILTER_FLAG_ENCODE_HIGH`, `FILTER_FLAG_ENCODE_AMP` | Strip tags, optionally strip or encode special characters.
`FILTER_SANITIZE_STRIPPED` | "stripped" |  |  | Alias of "string" filter.
`FILTER_SANITIZE_ENCODED` | "encoded" |  | `FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_LOW`, `FILTER_FLAG_ENCODE_HIGH` | URL-encode string, optionally strip or encode special characters.
`FILTER_SANITIZE_SPECIAL_CHARS` | "special_chars" |  | `FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_HIGH` | HTML-escape '"<>& and characters with ASCII value less than 32, optionally strip or encode other special characters.
`FILTER_UNSAFE_RAW` | "unsafe_raw" |  | `FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_LOW`, `FILTER_FLAG_ENCODE_HIGH`, `FILTER_FLAG_ENCODE_AMP` | Do nothing, optionally strip or encode special characters.
`FILTER_SANITIZE_EMAIL` | "email" |  |  | Remove all characters except letters, digits and !#$%&'*+-/=?^_`{|}~@.[].
`FILTER_SANITIZE_URL` | "url" |  |  | Remove all characters except letters, digits and $-_.+!*'(),{}|\\^~[]`<>#%";/?:@&=.
`FILTER_SANITIZE_NUMBER_INT` | "number_int" |  |  | Remove all characters except digits and +-.
`FILTER_SANITIZE_NUMBER_FLOAT` | "number_float" |  | `FILTER_FLAG_ALLOW_FRACTION`, `FILTER_FLAG_ALLOW_THOUSAND`, `FILTER_FLAG_ALLOW_SCIENTIFIC` | Remove all characters except digits, +- and optionally .,eE.
`FILTER_SANITIZE_MAGIC_QUOTES` | "magic_quotes" |  |  | Apply addslashes().
`FILTER_CALLBACK` | "callback" | callback function or method |  | Call user-defined function to filter data.

## Requirements

No external libraries are needed to build this extension.

## Installation

A short installation note: just type

    $ pecl install filter

in your console.

## Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Filter Configuration Options
Name | Default | Changeable | Changelog
--- | --- | --- | ---
filter.default | "unsafe_raw" | PHP_INI_PERDIR | PHP_INI_ALL in filter <= 0.9.4. Available since PHP 5.2.0.
filter.default_flags | NULL | PHP_INI_PERDIR | PHP_INI_ALL in filter <= 0.9.4. Available since PHP 5.2.0.

For further details and definitions of the PHP_INI_* constants, see the php.ini directives.

Here's a short explanation of the configuration directives.

`filter.default` string

  Filter all $_GET, $_POST, $_COOKIE and $_REQUEST data by this filter. Original data can be accessed through filter_input().

  Accepts the name of the filter you like to use by default. See the existing filter list for the list of the filter names.

`filter.default_flags` integer

  Default flags

## Resource Types

This extension has no resource types defined.

## Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

`INPUT_POST` (integer)
  POST variables.
`INPUT_GET` (integer)
  GET variables.
`INPUT_COOKIE` (integer)
  COOKIE variables.
`INPUT_ENV` (integer)
  ENV variables.
`INPUT_SERVER` (integer)
  SERVER variables.
`INPUT_SESSION` (integer)
  SESSION variables. (not implemented yet)
`INPUT_REQUEST` (integer)
  REQUEST variables. (not implemented yet)
`FILTER_FLAG_NONE` (integer)
  No flags.
`FILTER_REQUIRE_SCALAR` (integer)
  Flag used to require scalar as input
`FILTER_REQUIRE_ARRAY` (integer)
  Require an array as input.
`FILTER_FORCE_ARRAY` (integer)
  Always returns an array.
`FILTER_NULL_ON_FAILURE` (integer)
  Use NULL instead of FALSE on failure.
`FILTER_VALIDATE_INT` (integer)
  ID of "int" filter.
`FILTER_VALIDATE_BOOLEAN` (integer)
  ID of "boolean" filter.
`FILTER_VALIDATE_FLOAT` (integer)
  ID of "float" filter.
`FILTER_VALIDATE_REGEXP` (integer)
  ID of "validate_regexp" filter.
`FILTER_VALIDATE_URL` (integer)
  ID of "validate_url" filter.
`FILTER_VALIDATE_EMAIL` (integer)
  ID of "validate_email" filter.
`FILTER_VALIDATE_IP` (integer)
  ID of "validate_ip" filter.
`FILTER_DEFAULT` (integer)
  ID of default ("string") filter.
`FILTER_UNSAFE_RAW` (integer)
  ID of "unsafe_raw" filter.
`FILTER_SANITIZE_STRING` (integer)
  ID of "string" filter.
`FILTER_SANITIZE_STRIPPED` (integer)
  ID of "stripped" filter.
`FILTER_SANITIZE_ENCODED` (integer)
  ID of "encoded" filter.
`FILTER_SANITIZE_SPECIAL_CHARS` (integer)
  ID of "special_chars" filter.
`FILTER_SANITIZE_EMAIL` (integer)
  ID of "email" filter.
`FILTER_SANITIZE_URL` (integer)
  ID of "url" filter.
`FILTER_SANITIZE_NUMBER_INT` (integer)
  ID of "number_int" filter.
`FILTER_SANITIZE_NUMBER_FLOAT` (integer)
  ID of "number_float" filter.
`FILTER_SANITIZE_MAGIC_QUOTES` (integer)
  ID of "magic_quotes" filter.
`FILTER_CALLBACK` (integer)
  ID of "callback" filter.
`FILTER_FLAG_ALLOW_OCTAL` (integer)
  Allow octal notation (0[0-7]+) in "int" filter.
`FILTER_FLAG_ALLOW_HEX` (integer)
  Allow hex notation (0x[0-9a-fA-F]+) in "int" filter.
`FILTER_FLAG_STRIP_LOW` (integer)
  Strip characters with ASCII value less than 32.
`FILTER_FLAG_STRIP_HIGH` (integer)
  Strip characters with ASCII value greater than 127.
`FILTER_FLAG_ENCODE_LOW` (integer)
  Encode characters with ASCII value less than 32.
`FILTER_FLAG_ENCODE_HIGH` (integer)
  Encode characters with ASCII value greater than 127.
`FILTER_FLAG_ENCODE_AMP` (integer)
  Encode &.
`FILTER_FLAG_NO_ENCODE_QUOTES` (integer)
  Don't encode ' and ".
`FILTER_FLAG_EMPTY_STRING_NULL` (integer)
  (No use for now.)
`FILTER_FLAG_ALLOW_FRACTION` (integer)
  Allow fractional part in "number_float" filter.
`FILTER_FLAG_ALLOW_THOUSAND` (integer)
  Allow thousand separator (,) in "number_float" filter.
`FILTER_FLAG_ALLOW_SCIENTIFIC` (integer)
  Allow scientific notation (e, E) in "number_float" filter.
`FILTER_FLAG_SCHEME_REQUIRED` (integer)
  Require scheme in "validate_url" filter.
`FILTER_FLAG_HOST_REQUIRED` (integer)
  Require host in "validate_url" filter.
`FILTER_FLAG_PATH_REQUIRED` (integer)
  Require path in "validate_url" filter.
`FILTER_FLAG_QUERY_REQUIRED` (integer)
  Require query in "validate_url" filter.
`FILTER_FLAG_IPV4` (integer)
  Allow only IPv4 address in "validate_ip" filter.
`FILTER_FLAG_IPV6` (integer)
  Allow only IPv6 address in "validate_ip" filter.
`FILTER_FLAG_NO_RES_RANGE` (integer)
  Deny reserved addresses in "validate_ip" filter.
`FILTER_FLAG_NO_PRIV_RANGE` (integer)
  Deny private addresses in "validate_ip" filter.

## Table of Contents

- filter_has_var — Checks if variable of specified type exists
- filter_id — Returns the filter ID belonging to a named filter
- filter_input_array — Gets multiple variables from outside PHP and optionally filters them
- filter_input — Gets variable from outside PHP and optionally filters it
- filter_list — Returns a list of all supported filters
- filter_var_array — Gets multiple variables and optionally filters them
- filter_var — Filters a variable with a specified filter