Last updated: Mon, 26 Nov 2007

Filter Functions

简介

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, plus and minus sign.
`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.

需求

要编译本扩展模块无需外部库文件。

安装

A short installation note: just type

$ pecl install filter

in your console.

运行时配置

这些函数的行为受 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.

有关 PHP_INI_* 常量进一步的细节与定义参见php.ini 配置选项。

以下是配置选项的简要解释。

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

资源类型

本扩展模块未定义任何资源类型。

预定义常量

以下常量由本扩展模块定义，因此只有在本扩展模块被编译到 PHP 中，或者在运行时被动态加载后才有效。

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.

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

filter_has_var

unlink

Last updated: Mon, 26 Nov 2007

add a note User Contributed Notes
Filter

Jovan Suervo
26-Nov-2007 05:35


It seems that all FILTER_VALIDATE_URL is doing is calling parse_url(), which makes it effectively useless since parse_url() only fails on really malformed urls.



<?php

$url = 'http://...';



var_dump(filter_var($url, FILTER_VALIDATE_URL));

?>



Will display: string(10) "http://..."



None of the flags help either, so you're better off with regular expressions to validate a url.

fumble1 at web dot de
13-Aug-2007 01:54


I recommend you to use the FILTER_REQUIRE_SCALAR (or FILTER_REQUIRE_ARRAY) flags, since you can use array-brackets both to access string offsets and array-element -- however, not only this can lead to unexpected behaviour. Look at this example:



<?php

$image = basename(filter_input(INPUT_GET, 'src', FILTER_UNSAFE_RAW, FILTER_FLAG_STRIP_LOW));

// further checks

?>



/script.php?src[0]=foobar will cause a warning. :-(

Hence my recommendation:



<?php

$image = basename(filter_input(INPUT_GET, 'src', FILTER_UNSAFE_RAW, FILTER_REQUIRE_SCALAR | FILTER_FLAG_STRIP_LOW));

// further checks

?>

Richard Davey rich at corephp dot co dot uk
14-Jun-2007 02:15


There is an undocumented filter flag for FILTER_VALIDATE_BOOLEAN. The documentation implies that it will return NULL if the value doesn't match the allowed true/false values. However this doesn't happen unless you give it the FILTER_NULL_ON_FAILURE flag like this:



<?php

$value = 'car';

$result = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);

?>



In the above $result will equal NULL. Without the extra flag it would equal FALSE, which isn't usually a desired result for this specific filter.

ckroll at rightmedia dot com
08-May-2007 11:02


Beware, the FILTER_SANITIZE_STRING flag functions much like strip_tags, so < will get filtered from input regardless of it's actually part of a tag.  We were getting unexepected results with a graphic library we wrote when trying to print < on a dynamic button.  The url came in something like ?string=%3C (<) but after filter ran it was empty.  To get around this, you could use FILTER_UNSAFE_RAW on that one param.

user
03-Feb-2007 04:15


Below is some code using filter API to restrict access to LAN by IPv4 private address range.



These notes may save someone else a little time:



filter_input_array() is useless for running multiple filters on the same key.

No way to chain or negate filters.



<?php



/* Merciful comment! */

function FILTER_NEGATE_HACK($_){ return (bool)!$_; }



function client_is_private_ipv4(){

  return (filter_input(INPUT_SERVER, 'REMOTE_ADDR', FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) && 

            FILTER_NEGATE_HACK(filter_input(INPUT_SERVER, 'REMOTE_ADDR', FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE));

}



if (! client_is_private_ipv4()) 

  exit('This application is restricted to local network users');



?>

vojtech at x dot cz
21-Dec-2006 10:38


Also notice that filter functions are using only the original variable values passed to the script even if you change the value in super global variable ($_GET, $_POST, ...) later in the script.



<?php

echo filter_input(INPUT_GET, 'var'); // print 'something'

echo $_GET['var']; // print 'something'

$_GET['var'] = 'changed';

echo filter_input(INPUT_GET, 'var'); // print 'something'

echo $_GET['var']; // print 'changed'

?>



In fact, external data are duplicated in SAPI before the script is processed and filter functions don't use super globals anymore (as explained in Filter tutorial bellow, section 'How does it work?').

vojtech at x dot cz
21-Dec-2006 09:13


Just to note that "server and env support may not work in all sapi, for filter 0.11.0 or php 5.2.0" as mentioned in Filter tutorial bellow.



The workaround is obvious:

Instead of 

<?php

$var = filter_input(INPUT_SERVER, 'SERVER_NAME', FILTER_DEFAULT);

?>

use

<?php

$var = filter_var(isset($_SERVER['SERVER_NAME']) ? $_SERVER['SERVER_NAME'] : NULL, FILTER_DEFAULT);

?>

kevin at oceania dot net
12-Nov-2006 01:34


Examples of ALL filters and flags here:

http://phpro.org/tutorials/Filtering-Data-with-PHP.html

philip at php dot net
01-Nov-2006 10:00


Filter tutorial here:

 * http://devzone.zend.com/node/view/id/1113

add a note

filter_has_var

unlink

Last updated: Mon, 26 Nov 2007

Filter Functions

简介

需求

安装

运行时配置

资源类型

预定义常量

Table of Contents