Browse Source
Update filter docs and tests
Update filter docs and tests
Filter extension is better presented in the PHP manual. Some ext/filter/tests included outdated functions or were duplicated.pull/2816/merge
Peter Kokot
9 years ago
committed by
Joe Watkins
Joe Watkins
No known key found for this signature in database
GPG Key ID: F9BA0ADA31CBD89E
8 changed files with 9 additions and 436 deletions
-
331ext/filter/docs/filter.txt
-
41ext/filter/docs/input_get_args.php
-
4ext/filter/tests/006.phpt
-
4ext/filter/tests/011.phpt
-
2ext/filter/tests/032.phpt
-
4ext/filter/tests/036.phpt
-
55ext/filter/tests/bug7586.phpt
-
4ext/filter/tests/bug7733.phpt
@ -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,11 +1,11 @@ |
|||
--TEST-- |
|||
filter() test |
|||
filter_input() test |
|||
--SKIPIF-- |
|||
<?php if (!extension_loaded("filter")) die("skip"); ?> |
|||
--POST-- |
|||
foo=<b>abc</b> |
|||
--FILE-- |
|||
<?php |
|||
<?php |
|||
echo filter_input(INPUT_POST, 'foo', FILTER_SANITIZE_STRIPPED); |
|||
?> |
|||
--EXPECT-- |
|||
|
|||
@ -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) |
|||
} |
|||
} |
|||
Write
Preview
Loading…
Cancel
Save
Reference in new issue