filter.txt

PHP v6.0 For Linux 运行环境：Win9X/ WinME/ WinNT/ Win2K/ WinXP

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.