mirror of
https://github.com/php/php-src.git
synced 2024-11-28 20:34:29 +08:00
Update filter docs and tests
Filter extension is better presented in the PHP manual. Some ext/filter/tests included outdated functions or were duplicated.
This commit is contained in:
Peter Kokot
Joe Watkins
parent
d2754810cd
commit
2bc23f8028
@ -1,331 +0,0 @@
|
||||
Input Filter Extension
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Introduction
|
||||
============
|
||||
We all know that you should always check input variables, but PHP does not
|
||||
offer really good functionality for doing this in a safe way. The Input Filter
|
||||
extension is meant to address this issue by implementing a set of filters and
|
||||
mechanisms that users can use to safely access their input data.
|
||||
|
||||
|
||||
Change Log
|
||||
==========
|
||||
2005-10-27
|
||||
* Updated filter_data prototype
|
||||
* Added filter constants
|
||||
* Fixed minor problems
|
||||
* Changes by David Tulloh
|
||||
|
||||
2005-10-05
|
||||
* Changed "input_filter.paranoid_admin_default_filter" to
|
||||
"filter.default".
|
||||
* Updated API prototypes to reflect implementation.
|
||||
* Added 'on' and 'off' to the boolean filter.
|
||||
* Removed min_range and max_range flags from the float filter.
|
||||
* Added validate_url, validate_email and validate_ip filters.
|
||||
* Updated allows flags for all filters.
|
||||
|
||||
2005-08-15
|
||||
* Unmade *source* a bitmask, it doesn't make sense to do.
|
||||
* Changed return value of filters which got invalid data from 'false' to
|
||||
'null.
|
||||
* Failed filters do not throw an E_NOTICE any longer.
|
||||
* Added a magic_quotes sanitizing filter.
|
||||
|
||||
|
||||
General Considerations
|
||||
======================
|
||||
* If the filter's expected input data mask does not match the provided data
|
||||
for logical filters the filter function returns "false". If the data was
|
||||
not found, "null" is returned.
|
||||
* Character filters always return a string.
|
||||
* With the input filter extension enabled, and the
|
||||
input_filter.paranoid_admin_default_filter is set to something != 'raw',
|
||||
then all entries in the affected super globals will be passed through the
|
||||
configured filter. The 'callback' filter can not be used here, as that
|
||||
requieres a PHP script to be running already.
|
||||
* As the input filter acts on input data before the magic quotes function
|
||||
mangles data, all access through the filter() function will not have any
|
||||
quotes or slashes added - it will be the pure data as send by the browser.
|
||||
* All flags mentioned here should be prepended with `FILTER_FLAG_` when used
|
||||
with PHP.
|
||||
|
||||
|
||||
API
|
||||
===
|
||||
mixed *input_get* (int *source*, string *name*, [, int *filter* [, mixed *filter_options*, [ string *characterset* ] ]);
|
||||
Returns the filtered variable *$name* from source *$source*. It uses the
|
||||
filter as specified in *$filter* with a constant, and additional options
|
||||
to the filter through *$filter_options*.
|
||||
|
||||
mixed *input_get_args* (array *definitions*, int *source*, [, array *data*]);
|
||||
Returns an array with all filtered variables defined in 'definition'.
|
||||
The keys are used as the name of the argument. The value can be either
|
||||
an integer (flags) or an array of options. This array can contain
|
||||
the 'filter' type, the 'flags', the 'otptions' or the 'charset'
|
||||
|
||||
bool *input_has_variable (int *source*, string *name*);
|
||||
Returns *true* if the variable with the name *name* exists in *source*, or
|
||||
*false* otherwise.
|
||||
|
||||
array *input_filters_list* ();
|
||||
Returns a list with all supported filter names.
|
||||
|
||||
mixed *filter_data* (mixed *variable*, int *filter* [, mixed *filter_options*, [ string *characterset* ] ]);
|
||||
Filters the user supplied variable *$variable* in the same manner as
|
||||
*input_get*.
|
||||
|
||||
*$source*:
|
||||
|
||||
* INPUT_POST 0
|
||||
* INPUT_GET 1
|
||||
* INPUT_COOKIE 2
|
||||
* INPUT_ENV 4
|
||||
* INPUT_SERVER 5 (not implemented yet)
|
||||
* INPUT_SESSION 6 (not implemented yet)
|
||||
|
||||
|
||||
General flags
|
||||
=============
|
||||
|
||||
* FILTER_FLAG_SCALAR
|
||||
* FILTER_FLAG_ARRAY
|
||||
|
||||
These two constants define whether to allow arrays in the source values. The
|
||||
default value is SCALAR for input_get_args and ARRAY for the other functions
|
||||
(< 0.9.5). These constants also insure that the function returns the correct
|
||||
type, if you ask for an array, you will get an array even if the source is
|
||||
only one value. However, if you ask for a scalar and the source is an array,
|
||||
the result will be FALSE (invalid).
|
||||
|
||||
|
||||
Logical Filters
|
||||
===============
|
||||
|
||||
These filters check whether passed data was valid, and do never mangle input
|
||||
variables, but ofcourse they can deny the whole input variable getting to the
|
||||
application by returning false.
|
||||
|
||||
The constants should be prepended by `FILTER_VALIDATE_` when used with php.
|
||||
|
||||
================ ========== =========== ==================================================
|
||||
Name Constant Return Type Description
|
||||
================ ========== =========== ==================================================
|
||||
int INT integer Returns the input variable as an integer
|
||||
|
||||
$filter_options - an array with the optional
|
||||
elements:
|
||||
|
||||
* min_range: Minimal number that is allowed
|
||||
(inclusive)
|
||||
* max_range: Maximum number that is allowed
|
||||
(inclusive)
|
||||
* flags: A bitmask supporting the following flags:
|
||||
|
||||
- ALLOW_OCTAL: allow octal numbers with the format
|
||||
0nn as input too.
|
||||
- ALLOW_HEX: allow hexadecimal numbers with the
|
||||
format 0xnn or 0Xnn too.
|
||||
|
||||
boolean BOOLEAN boolean Returns *true* for '1', 'on' and 'true' and *false*
|
||||
for '0', 'off' and 'false'
|
||||
|
||||
float FLOAT float Returns the input variable as a floating point value
|
||||
|
||||
validate_regexp REGEXP string Matches the input value as a string against the
|
||||
regular expression. If there is a match then the
|
||||
string is returned, otherwise the filter returns
|
||||
*null*.
|
||||
Remarks: Only available if pcre has been compiled
|
||||
into PHP.
|
||||
|
||||
validate_url URL string Validates an URL's format.
|
||||
|
||||
$filter_options - an bitmask that supports the
|
||||
following flags:
|
||||
|
||||
* SCHEME_REQUIRED: The 'schema' part of the URL
|
||||
needs to in the passed URL.
|
||||
* HOST_REQUIRED: The 'host' part of the URL
|
||||
needs to in the passed URL.
|
||||
* PATH_REQUIRED: The 'path' part of the URL
|
||||
needs to in the passed URL.
|
||||
* QUERY_REQUIRED: The 'query' part of the URL
|
||||
needs to in the passed URL.
|
||||
|
||||
validate_email EMAIL string Validates the passed string against a reasonably
|
||||
good regular expression for validating an email
|
||||
address.
|
||||
|
||||
validate_ip IP string Validates a string representing an IP address.
|
||||
|
||||
$filter_options - an bitmask that supports the
|
||||
following flags:
|
||||
|
||||
* IPV4: Allows IPv4 addresses.
|
||||
* IPV6: Allows IPv6 addresses.
|
||||
* NO_RES_RANGE: Disallows addresses in reversed
|
||||
ranges (IPv4 only)
|
||||
* NO_PRIV_RANGE: Disallows addresses in private
|
||||
ranges (IPv4 only)
|
||||
================ ========== =========== ==================================================
|
||||
|
||||
|
||||
Sanitizing Filters
|
||||
==================
|
||||
|
||||
These filters remove data, or change data depending on the filter, and the
|
||||
set rules for this specific filter. Instead of taking an *options* array, they
|
||||
use this parameter for flags for the specific filter.
|
||||
|
||||
The constants should be prepended by `FILTER_SANITIZE_` when used with php.
|
||||
|
||||
============= ================ =========== =====================================================
|
||||
Name Constant Return Type Description
|
||||
============= ================ =========== =====================================================
|
||||
string STRING string Returns the input variable as a string after it has
|
||||
been stripped of XML/HTML tags and other evil things
|
||||
that can cause XSS problems.
|
||||
|
||||
$filter_options - an bitmask that supports the
|
||||
following flags:
|
||||
|
||||
* NO_ENCODE_QUOTES: Prevents single and double
|
||||
quotes from being encoded as numerical HTML
|
||||
entities.
|
||||
* STRIP_LOW: excludes all characters < 0x20 from the
|
||||
allowed character list
|
||||
* STRIP_HIGH: excludes all characters >= 0x80 from
|
||||
the allowed character list
|
||||
* ENCODE_LOW: allows characters < 0x20 but encodes
|
||||
them as numerical HTML entities
|
||||
* ENCODE_HIGH: allows characters >= 0x80 but encodes
|
||||
them as numerical HTML entities
|
||||
* ENCODE_AMP: encodes & as &
|
||||
|
||||
The flags STRIP_LOW and ENCODE_LOW are mutual
|
||||
exclusive, and so are STRIP_HIGH and ENCODE_HIGH. In
|
||||
the case they clash, the characters will be
|
||||
stripped.
|
||||
|
||||
stripped STRIPPED string Alias for 'string'.
|
||||
|
||||
encoded ENCODED string Encodes all characters outside the range
|
||||
"a-zA-Z0-9-._" as URL encoded values.
|
||||
|
||||
$filter_options - an bitmask that supports the
|
||||
following flags:
|
||||
|
||||
* STRIP_LOW: excludes all characters < 0x20 from the
|
||||
allowed character list
|
||||
* STRIP_HIGH: excludes all characters >= 0x80 from
|
||||
the allowed character list
|
||||
* ENCODE_LOW: allows characters < 0x20 but encodes
|
||||
them as numerical HTML entities
|
||||
* ENCODE_HIGH: allows characters >= 0x80 but encodes
|
||||
them as numerical HTML entities
|
||||
|
||||
special_chars SPECIAL_CHARS string Encodes the 'special' characters ' " < > &, \0 and
|
||||
everything below 0x20 as numerical HTML entities.
|
||||
|
||||
$filter_options - an bitmask that supports the
|
||||
following flags:
|
||||
|
||||
* STRIP_LOW: excludes all characters < 0x20 from the
|
||||
allowed character list. If this is not set, then
|
||||
those characters are encoded as numerical HTML
|
||||
entities
|
||||
* STRIP_HIGH: excludes all characters >= 0x80 from
|
||||
the allowed character list
|
||||
* ENCODE_HIGH: allows characters >= 0x80 but encodes
|
||||
them as numerical HTML entities
|
||||
|
||||
unsafe_raw UNSAFE_RAW string Returns the input variable as a string without
|
||||
XML/HTML being stripped from the input value.
|
||||
|
||||
$filter_options - an bitmask that supports the
|
||||
following flags:
|
||||
|
||||
* STRIP_LOW: excludes all characters < 0x20 from the
|
||||
allowed character list
|
||||
* STRIP_HIGH: excludes all characters >= 0x80 from
|
||||
the allowed character list
|
||||
* ENCODE_LOW: allows characters < 0x20 but encodes
|
||||
them as numerical HTML entities
|
||||
* ENCODE_HIGH: allows characters >= 0x80 but encodes
|
||||
them as numerical HTML entities
|
||||
* ENCODE_AMP: encodes & as &
|
||||
|
||||
The flags STRIP_LOW and ENCODE_LOW are mutual
|
||||
exclusive, and so are STRIP_HIGH and ENCODE_HIGH. In
|
||||
the case they clash, the characters will be
|
||||
stripped.
|
||||
|
||||
email EMAIL string Removes all characters that can not be part of a
|
||||
correctly formed e-mail address (exception are
|
||||
comments in the email address) (a-z A-Z 0-9 " ! # $
|
||||
% & ' * + - / = ? ^ _ ` { | } ~ @ . [ ]). This
|
||||
filter does `not` validate if the e-mail address has
|
||||
the correct format, use the validate_email filter
|
||||
for that.
|
||||
|
||||
url URL string Removes all characters that can not be part of a
|
||||
correctly formed URI. (a-z A-Z 0-9 $ - _ . + ! * ' (
|
||||
) , { } | \ ^ ~ [ ] ` < > # % " ; / ? : @ & =) This
|
||||
filter does `not` validate if a URI has the correct
|
||||
format, use the validate_url filter for that.
|
||||
|
||||
number_int NUMBER_INT int Removes all characters that are [^0-9+-].
|
||||
|
||||
number_float NUMBER_FLOAT float Removes all characters that are [^0-9+-].
|
||||
|
||||
$filter_options - an bitmask that supports the
|
||||
following flags:
|
||||
|
||||
* ALLOW_FRACTION: adds "." to the characters that
|
||||
are not stripped.
|
||||
* ALLOW_THOUSAND: adds "," to the characters that
|
||||
are not stripped.
|
||||
* ALLOW_SCIENTIFIC: adds "eE" to the characters that
|
||||
are not stripped.
|
||||
|
||||
magic_quotes MAGIC_QUOTES string BC filter for people who like magic quotes.
|
||||
============= ================ =========== =====================================================
|
||||
|
||||
|
||||
Callback Filter
|
||||
===============
|
||||
|
||||
This filter will callback to the specified callback function as specified with
|
||||
the *filter_options* parameter. All variants of callback functions are
|
||||
supported:
|
||||
|
||||
* function with *'functionname'*
|
||||
* static method with *array('classname', 'methodname')*
|
||||
* dynamic method with *array(&$this, 'methodname')*
|
||||
|
||||
The constants should be prepended by `FILTER_` when used with php.
|
||||
|
||||
============= =========== =========== =====================================================
|
||||
Name Constant Return Type Description
|
||||
============= =========== =========== =====================================================
|
||||
callback CALLBACK mixed Calls the callback function/method with the input
|
||||
variable's value by reference which can do filtering
|
||||
and modifying of the input value. If the callback
|
||||
function returns "false" then the input value is
|
||||
supposed to be incorrect and the returned value will
|
||||
be 'false' (and an E_NOTICE will be raised).
|
||||
============= =========== =========== =====================================================
|
||||
|
||||
The callback function's prototype is:
|
||||
|
||||
boolean callback(&$value, $characterset);
|
||||
With *$value* being a reference to the input variable and *$characterset*
|
||||
containing the same value as this parameter's value in the call to
|
||||
*input_get()* or *input_get_array()*. If the *$characterset* parameter was
|
||||
not passed, it defaults to *'null'*.
|
||||
|
||||
Version: $Id$
|
||||
.. vim: et syn=rst tw=78
|
||||
|
||||
@ -1,41 +0,0 @@
|
||||
<?php
|
||||
error_reporting(E_ALL|E_STRICT);
|
||||
$data = array(
|
||||
'product_id' => 'product id<script>',
|
||||
'component' => '10',
|
||||
'versions' => '1.2.33',
|
||||
'testscalar' => array('2','23','10','12'),
|
||||
'testarray' => '2',
|
||||
);
|
||||
|
||||
$args = array(
|
||||
'product_id' => FILTER_SANITIZE_ENCODED,
|
||||
'component' => array('filter' => FILTER_VALIDATE_INT,
|
||||
'flags' => FILTER_FLAG_ARRAY,
|
||||
'options' => array("min_range"=>1, "max_range"=>10)
|
||||
),
|
||||
|
||||
/* equivalent of => FILTER_SANITIZE_ENCODED as SCALAR is
|
||||
* the default mode
|
||||
*/
|
||||
'versions' => array(
|
||||
'filter' => FILTER_SANITIZE_ENCODED,
|
||||
'flags' => FILTER_FLAG_SCALAR,
|
||||
),
|
||||
'doesnotexist' => FILTER_VALIDATE_INT,
|
||||
'testscalar' => FILTER_VALIDATE_INT,
|
||||
'testarray' => array(
|
||||
'filter' => FILTER_VALIDATE_INT,
|
||||
'flags' => FILTER_FLAG_ARRAY,
|
||||
)
|
||||
|
||||
);
|
||||
|
||||
/*
|
||||
The other INPUT_* can be used as well.
|
||||
$myinputs = input_get_args($args, INPUT_POST);
|
||||
*/
|
||||
$myinputs = input_get_args($args, INPUT_DATA, $data);
|
||||
|
||||
var_dump($myinputs);
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
--TEST--
|
||||
filter() test
|
||||
filter_input() test
|
||||
--SKIPIF--
|
||||
<?php if (!extension_loaded("filter")) die("skip"); ?>
|
||||
--POST--
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
--TEST--
|
||||
input_get()
|
||||
filter_input()
|
||||
--INI--
|
||||
precision=14
|
||||
--SKIPIF--
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
--TEST--
|
||||
input_get_args()
|
||||
filter_var_array()
|
||||
--SKIPIF--
|
||||
<?php if (!extension_loaded("filter")) die("skip"); ?>
|
||||
--FILE--
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
--TEST--
|
||||
input_get_args() and references
|
||||
filter_var_array() and references
|
||||
--SKIPIF--
|
||||
<?php if (!extension_loaded("filter")) print "skip"; ?>
|
||||
--FILE--
|
||||
|
||||
@ -1,55 +0,0 @@
|
||||
--TEST--
|
||||
input_get_args() filter not reseted between elements
|
||||
--SKIPIF--
|
||||
<?php if (!extension_loaded("filter")) die("skip"); ?>
|
||||
--FILE--
|
||||
<?php
|
||||
$data = array(
|
||||
'product_id' => 'libgd<script>',
|
||||
'component' => '10dhsajkkdhk <do>',
|
||||
'versions' => '2.0.33',
|
||||
'testscalar' => array('2','23','10','12'),
|
||||
'testarray' => '2',
|
||||
);
|
||||
|
||||
$args = array(
|
||||
'product_id' => FILTER_SANITIZE_ENCODED,
|
||||
'component' => array('flags' => FILTER_FORCE_ARRAY,
|
||||
'options' => array("min_range"=>1, "max_range"=>10)
|
||||
),
|
||||
'versions' => array(
|
||||
'filter' => FILTER_SANITIZE_ENCODED,
|
||||
'flags' => FILTER_REQUIRE_SCALAR,
|
||||
),
|
||||
'doesnotexist' => FILTER_VALIDATE_INT,
|
||||
'testscalar' => FILTER_VALIDATE_INT,
|
||||
'testarray' => array(
|
||||
'filter' => FILTER_VALIDATE_INT,
|
||||
'flags' => FILTER_FORCE_ARRAY,
|
||||
)
|
||||
|
||||
);
|
||||
$out = filter_var_array($data, $args);
|
||||
var_dump($out);
|
||||
?>
|
||||
--EXPECTF--
|
||||
array(6) {
|
||||
["product_id"]=>
|
||||
string(17) "libgd%3Cscript%3E"
|
||||
["component"]=>
|
||||
array(1) {
|
||||
[0]=>
|
||||
string(17) "%s"
|
||||
}
|
||||
["versions"]=>
|
||||
string(6) "2.0.33"
|
||||
["doesnotexist"]=>
|
||||
NULL
|
||||
["testscalar"]=>
|
||||
bool(false)
|
||||
["testarray"]=>
|
||||
array(1) {
|
||||
[0]=>
|
||||
int(2)
|
||||
}
|
||||
}
|
||||
@ -1,5 +1,5 @@
|
||||
--TEST--
|
||||
filter_data() Float exponential weird result
|
||||
filter_var() Float exponential weird result
|
||||
--SKIPIF--
|
||||
<?php if (!extension_loaded("filter")) die("skip"); ?>
|
||||
--FILE--
|
||||
|
||||
Loading…
Reference in New Issue
Block a user