Annotation of embedaddon/php/ext/filter/docs/filter.txt, revision 1.1
1.1 ! misho 1: Input Filter Extension
! 2: ~~~~~~~~~~~~~~~~~~~~~~
! 3:
! 4: Introduction
! 5: ============
! 6: We all know that you should always check input variables, but PHP does not
! 7: offer really good functionality for doing this in a safe way. The Input Filter
! 8: extension is meant to address this issue by implementing a set of filters and
! 9: mechanisms that users can use to safely access their input data.
! 10:
! 11:
! 12: Change Log
! 13: ==========
! 14: 2005-10-27
! 15: * Updated filter_data prototype
! 16: * Added filter constants
! 17: * Fixed minor problems
! 18: * Changes by David Tulloh
! 19:
! 20: 2005-10-05
! 21: * Changed "input_filter.paranoid_admin_default_filter" to
! 22: "filter.default".
! 23: * Updated API prototypes to reflect implementation.
! 24: * Added 'on' and 'off' to the boolean filter.
! 25: * Removed min_range and max_range flags from the float filter.
! 26: * Added validate_url, validate_email and validate_ip filters.
! 27: * Updated allows flags for all filters.
! 28:
! 29: 2005-08-15
! 30: * Unmade *source* a bitmask, it doesn't make sense to do.
! 31: * Changed return value of filters which got invalid data from 'false' to
! 32: 'null.
! 33: * Failed filters do not throw an E_NOTICE any longer.
! 34: * Added a magic_quotes sanitizing filter.
! 35:
! 36:
! 37: General Considerations
! 38: ======================
! 39: * If the filter's expected input data mask does not match the provided data
! 40: for logical filters the filter function returns "false". If the data was
! 41: not found, "null" is returned.
! 42: * Character filters always return a string.
! 43: * With the input filter extension enabled, and the
! 44: input_filter.paranoid_admin_default_filter is set to something != 'raw',
! 45: then all entries in the affected super globals will be passed through the
! 46: configured filter. The 'callback' filter can not be used here, as that
! 47: requieres a PHP script to be running already.
! 48: * As the input filter acts on input data before the magic quotes function
! 49: mangles data, all access through the filter() function will not have any
! 50: quotes or slashes added - it will be the pure data as send by the browser.
! 51: * All flags mentioned here should be prepended with `FILTER_FLAG_` when used
! 52: with PHP.
! 53:
! 54:
! 55: API
! 56: ===
! 57: mixed *input_get* (int *source*, string *name*, [, int *filter* [, mixed *filter_options*, [ string *characterset* ] ]);
! 58: Returns the filtered variable *$name* from source *$source*. It uses the
! 59: filter as specified in *$filter* with a constant, and additional options
! 60: to the filter through *$filter_options*.
! 61:
! 62: mixed *input_get_args* (array *definitions*, int *source*, [, array *data*]);
! 63: Returns an array with all filtered variables defined in 'definition'.
! 64: The keys are used as the name of the argument. The value can be either
! 65: an integer (flags) or an array of options. This array can contain
! 66: the 'filter' type, the 'flags', the 'otptions' or the 'charset'
! 67:
! 68: bool *input_has_variable (int *source*, string *name*);
! 69: Returns *true* if the variable with the name *name* exists in *source*, or
! 70: *false* otherwise.
! 71:
! 72: array *input_filters_list* ();
! 73: Returns a list with all supported filter names.
! 74:
! 75: mixed *filter_data* (mixed *variable*, int *filter* [, mixed *filter_options*, [ string *characterset* ] ]);
! 76: Filters the user supplied variable *$variable* in the same manner as
! 77: *input_get*.
! 78:
! 79: *$source*:
! 80:
! 81: * INPUT_POST 0
! 82: * INPUT_GET 1
! 83: * INPUT_COOKIE 2
! 84: * INPUT_ENV 4
! 85: * INPUT_SERVER 5 (not implemented yet)
! 86: * INPUT_SESSION 6 (not implemented yet)
! 87:
! 88:
! 89: General flags
! 90: =============
! 91:
! 92: * FILTER_FLAG_SCALAR
! 93: * FILTER_FLAG_ARRAY
! 94:
! 95: These two constants define whether to allow arrays in the source values. The
! 96: default value is SCALAR for input_get_args and ARRAY for the other functions
! 97: (< 0.9.5). These constants also insure that the function returns the correct
! 98: type, if you ask for an array, you will get an array even if the source is
! 99: only one value. However, if you ask for a scalar and the source is an array,
! 100: the result will be FALSE (invalid).
! 101:
! 102:
! 103: Logical Filters
! 104: ===============
! 105:
! 106: These filters check whether passed data was valid, and do never mangle input
! 107: variables, but ofcourse they can deny the whole input variable getting to the
! 108: application by returning false.
! 109:
! 110: The constants should be prepended by `FILTER_VALIDATE_` when used with php.
! 111:
! 112: ================ ========== =========== ==================================================
! 113: Name Constant Return Type Description
! 114: ================ ========== =========== ==================================================
! 115: int INT integer Returns the input variable as an integer
! 116:
! 117: $filter_options - an array with the optional
! 118: elements:
! 119:
! 120: * min_range: Minimal number that is allowed
! 121: (inclusive)
! 122: * max_range: Maximum number that is allowed
! 123: (inclusive)
! 124: * flags: A bitmask supporting the following flags:
! 125:
! 126: - ALLOW_OCTAL: allow octal numbers with the format
! 127: 0nn as input too.
! 128: - ALLOW_HEX: allow hexadecimal numbers with the
! 129: format 0xnn or 0Xnn too.
! 130:
! 131: boolean BOOLEAN boolean Returns *true* for '1', 'on' and 'true' and *false*
! 132: for '0', 'off' and 'false'
! 133:
! 134: float FLOAT float Returns the input variable as a floating point value
! 135:
! 136: validate_regexp REGEXP string Matches the input value as a string against the
! 137: regular expression. If there is a match then the
! 138: string is returned, otherwise the filter returns
! 139: *null*.
! 140: Remarks: Only available if pcre has been compiled
! 141: into PHP.
! 142:
! 143: validate_url URL string Validates an URL's format.
! 144:
! 145: $filter_options - an bitmask that supports the
! 146: following flags:
! 147:
! 148: * SCHEME_REQUIRED: The 'schema' part of the URL
! 149: needs to in the passed URL.
! 150: * HOST_REQUIRED: The 'host' part of the URL
! 151: needs to in the passed URL.
! 152: * PATH_REQUIRED: The 'path' part of the URL
! 153: needs to in the passed URL.
! 154: * QUERY_REQUIRED: The 'query' part of the URL
! 155: needs to in the passed URL.
! 156:
! 157: validate_email EMAIL string Validates the passed string against a reasonably
! 158: good regular expression for validating an email
! 159: address.
! 160:
! 161: validate_ip IP string Validates a string representing an IP address.
! 162:
! 163: $filter_options - an bitmask that supports the
! 164: following flags:
! 165:
! 166: * IPV4: Allows IPv4 addresses.
! 167: * IPV6: Allows IPv6 addresses.
! 168: * NO_RES_RANGE: Disallows addresses in reversed
! 169: ranges (IPv4 only)
! 170: * NO_PRIV_RANGE: Disallows addresses in private
! 171: ranges (IPv4 only)
! 172: ================ ========== =========== ==================================================
! 173:
! 174:
! 175: Sanitizing Filters
! 176: ==================
! 177:
! 178: These filters remove data, or change data depending on the filter, and the
! 179: set rules for this specific filter. Instead of taking an *options* array, they
! 180: use this parameter for flags for the specific filter.
! 181:
! 182: The constants should be prepended by `FILTER_SANITIZE_` when used with php.
! 183:
! 184: ============= ================ =========== =====================================================
! 185: Name Constant Return Type Description
! 186: ============= ================ =========== =====================================================
! 187: string STRING string Returns the input variable as a string after it has
! 188: been stripped of XML/HTML tags and other evil things
! 189: that can cause XSS problems.
! 190:
! 191: $filter_options - an bitmask that supports the
! 192: following flags:
! 193:
! 194: * NO_ENCODE_QUOTES: Prevents single and double
! 195: quotes from being encoded as numerical HTML
! 196: entities.
! 197: * STRIP_LOW: excludes all characters < 0x20 from the
! 198: allowed character list
! 199: * STRIP_HIGH: excludes all characters >= 0x80 from
! 200: the allowed character list
! 201: * ENCODE_LOW: allows characters < 0x20 but encodes
! 202: them as numerical HTML entities
! 203: * ENCODE_HIGH: allows characters >= 0x80 but encodes
! 204: them as numerical HTML entities
! 205: * ENCODE_AMP: encodes & as &
! 206:
! 207: The flags STRIP_LOW and ENCODE_LOW are mutual
! 208: exclusive, and so are STRIP_HIGH and ENCODE_HIGH. In
! 209: the case they clash, the characters will be
! 210: stripped.
! 211:
! 212: stripped STRIPPED string Alias for 'string'.
! 213:
! 214: encoded ENCODED string Encodes all characters outside the range
! 215: "a-zA-Z0-9-._" as URL encoded values.
! 216:
! 217: $filter_options - an bitmask that supports the
! 218: following flags:
! 219:
! 220: * STRIP_LOW: excludes all characters < 0x20 from the
! 221: allowed character list
! 222: * STRIP_HIGH: excludes all characters >= 0x80 from
! 223: the allowed character list
! 224: * ENCODE_LOW: allows characters < 0x20 but encodes
! 225: them as numerical HTML entities
! 226: * ENCODE_HIGH: allows characters >= 0x80 but encodes
! 227: them as numerical HTML entities
! 228:
! 229: special_chars SPECIAL_CHARS string Encodes the 'special' characters ' " < > &, \0 and
! 230: everything below 0x20 as numerical HTML entities.
! 231:
! 232: $filter_options - an bitmask that supports the
! 233: following flags:
! 234:
! 235: * STRIP_LOW: excludes all characters < 0x20 from the
! 236: allowed character list. If this is not set, then
! 237: those characters are encoded as numerical HTML
! 238: entities
! 239: * STRIP_HIGH: excludes all characters >= 0x80 from
! 240: the allowed character list
! 241: * ENCODE_HIGH: allows characters >= 0x80 but encodes
! 242: them as numerical HTML entities
! 243:
! 244: unsafe_raw UNSAFE_RAW string Returns the input variable as a string without
! 245: XML/HTML being stripped from the input value.
! 246:
! 247: $filter_options - an bitmask that supports the
! 248: following flags:
! 249:
! 250: * STRIP_LOW: excludes all characters < 0x20 from the
! 251: allowed character list
! 252: * STRIP_HIGH: excludes all characters >= 0x80 from
! 253: the allowed character list
! 254: * ENCODE_LOW: allows characters < 0x20 but encodes
! 255: them as numerical HTML entities
! 256: * ENCODE_HIGH: allows characters >= 0x80 but encodes
! 257: them as numerical HTML entities
! 258: * ENCODE_AMP: encodes & as &
! 259:
! 260: The flags STRIP_LOW and ENCODE_LOW are mutual
! 261: exclusive, and so are STRIP_HIGH and ENCODE_HIGH. In
! 262: the case they clash, the characters will be
! 263: stripped.
! 264:
! 265: email EMAIL string Removes all characters that can not be part of a
! 266: correctly formed e-mail address (exception are
! 267: comments in the email address) (a-z A-Z 0-9 " ! # $
! 268: % & ' * + - / = ? ^ _ ` { | } ~ @ . [ ]). This
! 269: filter does `not` validate if the e-mail address has
! 270: the correct format, use the validate_email filter
! 271: for that.
! 272:
! 273: url URL string Removes all characters that can not be part of a
! 274: correctly formed URI. (a-z A-Z 0-9 $ - _ . + ! * ' (
! 275: ) , { } | \ ^ ~ [ ] ` < > # % " ; / ? : @ & =) This
! 276: filter does `not` validate if a URI has the correct
! 277: format, use the validate_url filter for that.
! 278:
! 279: number_int NUMBER_INT int Removes all characters that are [^0-9+-].
! 280:
! 281: number_float NUMBER_FLOAT float Removes all characters that are [^0-9+-].
! 282:
! 283: $filter_options - an bitmask that supports the
! 284: following flags:
! 285:
! 286: * ALLOW_FRACTION: adds "." to the characters that
! 287: are not stripped.
! 288: * ALLOW_THOUSAND: adds "," to the characters that
! 289: are not stripped.
! 290: * ALLOW_SCIENTIFIC: adds "eE" to the characters that
! 291: are not stripped.
! 292:
! 293: magic_quotes MAGIC_QUOTES string BC filter for people who like magic quotes.
! 294: ============= ================ =========== =====================================================
! 295:
! 296:
! 297: Callback Filter
! 298: ===============
! 299:
! 300: This filter will callback to the specified callback function as specified with
! 301: the *filter_options* parameter. All variants of callback functions are
! 302: supported:
! 303:
! 304: * function with *'functionname'*
! 305: * static method with *array('classname', 'methodname')*
! 306: * dynamic method with *array(&$this, 'methodname')*
! 307:
! 308: The constants should be prepended by `FILTER_` when used with php.
! 309:
! 310: ============= =========== =========== =====================================================
! 311: Name Constant Return Type Description
! 312: ============= =========== =========== =====================================================
! 313: callback CALLBACK mixed Calls the callback function/method with the input
! 314: variable's value by reference which can do filtering
! 315: and modifying of the input value. If the callback
! 316: function returns "false" then the input value is
! 317: supposed to be incorrect and the returned value will
! 318: be 'false' (and an E_NOTICE will be raised).
! 319: ============= =========== =========== =====================================================
! 320:
! 321: The callback function's prototype is:
! 322:
! 323: boolean callback(&$value, $characterset);
! 324: With *$value* being a reference to the input variable and *$characterset*
! 325: containing the same value as this parameter's value in the call to
! 326: *input_get()* or *input_get_array()*. If the *$characterset* parameter was
! 327: not passed, it defaults to *'null'*.
! 328:
! 329: Version: $Id: filter.txt 213641 2006-05-24 11:51:55Z pajoye $
! 330: .. vim: et syn=rst tw=78
! 331:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to filter.txt CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / ext / filter / docs