Annotation of embedaddon/php/ext/filter/docs/filter.txt, revision 1.1.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