+++ /dev/null
-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
-
projects / php / commitdiff