diff options
Diffstat (limited to 'ext/filter/docs')
| -rw-r--r-- | ext/filter/docs/filter.txt | 331 | ||||
| -rw-r--r-- | ext/filter/docs/input_get_args.php | 41 |
2 files changed, 372 insertions, 0 deletions
diff --git a/ext/filter/docs/filter.txt b/ext/filter/docs/filter.txt new file mode 100644 index 0000000..48aae0c --- /dev/null +++ b/ext/filter/docs/filter.txt @@ -0,0 +1,331 @@ +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 + diff --git a/ext/filter/docs/input_get_args.php b/ext/filter/docs/input_get_args.php new file mode 100644 index 0000000..b580524 --- /dev/null +++ b/ext/filter/docs/input_get_args.php @@ -0,0 +1,41 @@ +<?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); + |