Moved filter information into filters.xml and:

- Separated VALIDATE from SANITIZE (and MISC)
- Sorted lists alphabetically (by constant name)
- Removed constant intro, am rewriting a new one (will add soon to filters.xml)


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@277059 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2009-03-12 21:09:00 +00:00
parent 436cfd945e
commit 7160bbaa9d
2 changed files with 299 additions and 230 deletions

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- Purpose: basic.vartype -->
<book xml:id="book.filter" xmlns="http://docbook.org/ns/docbook">
@ -12,238 +12,10 @@
This extension serves to validate and filter data coming from some insecure
source, such as user input.
</para>
<para>
The following filters currently exist; be sure to read the
<link linkend="filter.constants">Filter Constants</link> section
for information that describes the behavior of each constant:
<table>
<title>Existing filters</title>
<tgroup cols="5">
<thead>
<row>
<entry>ID</entry>
<entry>Name</entry>
<entry>Options</entry>
<entry>Flags</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>FILTER_VALIDATE_INT</constant></entry>
<entry>"int"</entry>
<entry>
<parameter>min_range</parameter>,
<parameter>max_range</parameter>
</entry>
<entry>
<constant>FILTER_FLAG_ALLOW_OCTAL</constant>,
<constant>FILTER_FLAG_ALLOW_HEX</constant>
</entry>
<entry>Validates value as integer, optionally from the specified range.</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_BOOLEAN</constant></entry>
<entry>"boolean"</entry>
<entry></entry>
<entry>
<constant>FILTER_NULL_ON_FAILURE</constant>
</entry>
<entry>
<para>
Returns &true; for "1", "true", "on" and "yes".
Returns &false; otherwise.
</para>
<para>
If <constant>FILTER_NULL_ON_FAILURE</constant> is set, &false; is
returned only for "0", "false", "off", "no", and "", and
&null; is returned for all non-boolean values.
</para>
</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_FLOAT</constant></entry>
<entry>"float"</entry>
<entry>
<parameter>decimal</parameter>
</entry>
<entry>
<constant>FILTER_FLAG_ALLOW_THOUSAND</constant>
</entry>
<entry>Validates value as float.</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_REGEXP</constant></entry>
<entry>"validate_regexp"</entry>
<entry>
<parameter>regexp</parameter>
</entry>
<entry></entry>
<entry>
Validates value against <parameter>regexp</parameter>, a
<link linkend="book.pcre">Perl-compatible</link> regular expression.
</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_URL</constant></entry>
<entry>"validate_url"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_PATH_REQUIRED</constant>,
<constant>FILTER_FLAG_QUERY_REQUIRED</constant>
</entry>
<entry>Validates value as URL, optionally with required components.</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_EMAIL</constant></entry>
<entry>"validate_email"</entry>
<entry></entry>
<entry></entry>
<entry>Validates value as e-mail.</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_IP</constant></entry>
<entry>"validate_ip"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_IPV4</constant>,
<constant>FILTER_FLAG_IPV6</constant>,
<constant>FILTER_FLAG_NO_PRIV_RANGE</constant>,
<constant>FILTER_FLAG_NO_RES_RANGE</constant>
</entry>
<entry>
Validates value as IP address, optionally only IPv4 or IPv6 or not
from private or reserved ranges.
</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_STRING</constant></entry>
<entry>"string"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant>,
<constant>FILTER_FLAG_STRIP_LOW</constant>,
<constant>FILTER_FLAG_STRIP_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_LOW</constant>,
<constant>FILTER_FLAG_ENCODE_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_AMP</constant>
</entry>
<entry>Strip tags, optionally strip or encode special characters.</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_STRIPPED</constant></entry>
<entry>"stripped"</entry>
<entry></entry>
<entry></entry>
<entry>Alias of "string" filter.</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_ENCODED</constant></entry>
<entry>"encoded"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_STRIP_LOW</constant>,
<constant>FILTER_FLAG_STRIP_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_LOW</constant>,
<constant>FILTER_FLAG_ENCODE_HIGH</constant>
</entry>
<entry>URL-encode string, optionally strip or encode special characters.</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_SPECIAL_CHARS</constant></entry>
<entry>"special_chars"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_STRIP_LOW</constant>,
<constant>FILTER_FLAG_STRIP_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_HIGH</constant>
</entry>
<entry>
HTML-escape <literal>'"&lt;&gt;&amp;</literal> and characters with
ASCII value less than 32, optionally strip or encode other special
characters.
</entry>
</row>
<row>
<entry><constant>FILTER_UNSAFE_RAW</constant></entry>
<entry>"unsafe_raw"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_STRIP_LOW</constant>,
<constant>FILTER_FLAG_STRIP_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_LOW</constant>,
<constant>FILTER_FLAG_ENCODE_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_AMP</constant>
</entry>
<entry>Do nothing, optionally strip or encode special characters.</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_EMAIL</constant></entry>
<entry>"email"</entry>
<entry></entry>
<entry></entry>
<entry>
Remove all characters except letters, digits and
<literal>!#$%&amp;'*+-/=?^_`{|}~@.[]</literal>.
</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_URL</constant></entry>
<entry>"url"</entry>
<entry></entry>
<entry></entry>
<entry>
Remove all characters except letters, digits and
<literal>$-_.+!*'(),{}|\\^~[]`&lt;&gt;#%";/?:@&amp;=</literal>.
</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_NUMBER_INT</constant></entry>
<entry>"number_int"</entry>
<entry></entry>
<entry></entry>
<entry>
Remove all characters except digits, plus and minus sign.
</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_NUMBER_FLOAT</constant></entry>
<entry>"number_float"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_ALLOW_FRACTION</constant>,
<constant>FILTER_FLAG_ALLOW_THOUSAND</constant>,
<constant>FILTER_FLAG_ALLOW_SCIENTIFIC</constant>
</entry>
<entry>
Remove all characters except digits, <literal>+-</literal> and
optionally <literal>.,eE</literal>.
</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_MAGIC_QUOTES</constant></entry>
<entry>"magic_quotes"</entry>
<entry></entry>
<entry></entry>
<entry>Apply <function>addslashes</function>.</entry>
</row>
<row>
<entry><constant>FILTER_CALLBACK</constant></entry>
<entry>"callback"</entry>
<entry><type>callback</type> function or method</entry>
<entry></entry>
<entry>Call user-defined function to filter data.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</preface>
&reference.filter.setup;
&reference.filter.filters;
&reference.filter.constants;
&reference.filter.reference;

View file

@ -0,0 +1,297 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<chapter xml:id="filter.filters" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Types of filters</title>
<section xml:id='filter.filters.valiate'>
<title>Validate filters</title>
<para>
<table>
<title>Listing of filters for validation</title>
<tgroup cols="5">
<thead>
<row>
<entry>ID</entry>
<entry>Name</entry>
<entry>Options</entry>
<entry>Flags</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>FILTER_VALIDATE_BOOLEAN</constant></entry>
<entry>"boolean"</entry>
<entry></entry>
<entry>
<constant>FILTER_NULL_ON_FAILURE</constant>
</entry>
<entry>
<para>
Returns &true; for "1", "true", "on" and "yes".
Returns &false; otherwise.
</para>
<para>
If <constant>FILTER_NULL_ON_FAILURE</constant> is set, &false; is
returned only for "0", "false", "off", "no", and "", and
&null; is returned for all non-boolean values.
</para>
</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_EMAIL</constant></entry>
<entry>"validate_email"</entry>
<entry></entry>
<entry></entry>
<entry>Validates value as e-mail.</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_FLOAT</constant></entry>
<entry>"float"</entry>
<entry>
<parameter>decimal</parameter>
</entry>
<entry>
<constant>FILTER_FLAG_ALLOW_THOUSAND</constant>
</entry>
<entry>Validates value as float.</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_INT</constant></entry>
<entry>"int"</entry>
<entry>
<parameter>min_range</parameter>,
<parameter>max_range</parameter>
</entry>
<entry>
<constant>FILTER_FLAG_ALLOW_OCTAL</constant>,
<constant>FILTER_FLAG_ALLOW_HEX</constant>
</entry>
<entry>Validates value as integer, optionally from the specified range.</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_IP</constant></entry>
<entry>"validate_ip"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_IPV4</constant>,
<constant>FILTER_FLAG_IPV6</constant>,
<constant>FILTER_FLAG_NO_PRIV_RANGE</constant>,
<constant>FILTER_FLAG_NO_RES_RANGE</constant>
</entry>
<entry>
Validates value as IP address, optionally only IPv4 or IPv6 or not
from private or reserved ranges.
</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_REGEXP</constant></entry>
<entry>"validate_regexp"</entry>
<entry>
<parameter>regexp</parameter>
</entry>
<entry></entry>
<entry>
Validates value against <parameter>regexp</parameter>, a
<link linkend="book.pcre">Perl-compatible</link> regular expression.
</entry>
</row>
<row>
<entry><constant>FILTER_VALIDATE_URL</constant></entry>
<entry>"validate_url"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_PATH_REQUIRED</constant>,
<constant>FILTER_FLAG_QUERY_REQUIRED</constant>
</entry>
<entry>Validates value as URL, optionally with required components.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section xml:id='filter.filters.sanitize'>
<title>Sanitize filters</title>
<para>
<table>
<title>List of filters for sanitization</title>
<tgroup cols="5">
<thead>
<row>
<entry>ID</entry>
<entry>Name</entry>
<entry>Options</entry>
<entry>Flags</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>FILTER_SANITIZE_EMAIL</constant></entry>
<entry>"email"</entry>
<entry></entry>
<entry></entry>
<entry>
Remove all characters except letters, digits and
<literal>!#$%&amp;'*+-/=?^_`{|}~@.[]</literal>.
</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_ENCODED</constant></entry>
<entry>"encoded"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_STRIP_LOW</constant>,
<constant>FILTER_FLAG_STRIP_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_LOW</constant>,
<constant>FILTER_FLAG_ENCODE_HIGH</constant>
</entry>
<entry>URL-encode string, optionally strip or encode special characters.</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_MAGIC_QUOTES</constant></entry>
<entry>"magic_quotes"</entry>
<entry></entry>
<entry></entry>
<entry>Apply <function>addslashes</function>.</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_NUMBER_FLOAT</constant></entry>
<entry>"number_float"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_ALLOW_FRACTION</constant>,
<constant>FILTER_FLAG_ALLOW_THOUSAND</constant>,
<constant>FILTER_FLAG_ALLOW_SCIENTIFIC</constant>
</entry>
<entry>
Remove all characters except digits, <literal>+-</literal> and
optionally <literal>.,eE</literal>.
</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_NUMBER_INT</constant></entry>
<entry>"number_int"</entry>
<entry></entry>
<entry></entry>
<entry>
Remove all characters except digits, plus and minus sign.
</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_SPECIAL_CHARS</constant></entry>
<entry>"special_chars"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_STRIP_LOW</constant>,
<constant>FILTER_FLAG_STRIP_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_HIGH</constant>
</entry>
<entry>
HTML-escape <literal>'"&lt;&gt;&amp;</literal> and characters with
ASCII value less than 32, optionally strip or encode other special
characters.
</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_STRING</constant></entry>
<entry>"string"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant>,
<constant>FILTER_FLAG_STRIP_LOW</constant>,
<constant>FILTER_FLAG_STRIP_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_LOW</constant>,
<constant>FILTER_FLAG_ENCODE_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_AMP</constant>
</entry>
<entry>Strip tags, optionally strip or encode special characters.</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_STRIPPED</constant></entry>
<entry>"stripped"</entry>
<entry></entry>
<entry></entry>
<entry>Alias of "string" filter.</entry>
</row>
<row>
<entry><constant>FILTER_SANITIZE_URL</constant></entry>
<entry>"url"</entry>
<entry></entry>
<entry></entry>
<entry>
Remove all characters except letters, digits and
<literal>$-_.+!*'(),{}|\\^~[]`&lt;&gt;#%";/?:@&amp;=</literal>.
</entry>
</row>
<row>
<entry><constant>FILTER_UNSAFE_RAW</constant></entry>
<entry>"unsafe_raw"</entry>
<entry></entry>
<entry>
<constant>FILTER_FLAG_STRIP_LOW</constant>,
<constant>FILTER_FLAG_STRIP_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_LOW</constant>,
<constant>FILTER_FLAG_ENCODE_HIGH</constant>,
<constant>FILTER_FLAG_ENCODE_AMP</constant>
</entry>
<entry>Do nothing, optionally strip or encode special characters.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section xml:id='filter.filters.misc'>
<title>Other filters</title>
<para>
<table>
<title>List of miscellaneous filters</title>
<tgroup cols="5">
<thead>
<row>
<entry>ID</entry>
<entry>Name</entry>
<entry>Options</entry>
<entry>Flags</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>FILTER_CALLBACK</constant></entry>
<entry>"callback"</entry>
<entry><type>callback</type> function or method</entry>
<entry></entry>
<entry>Call user-defined function to filter data.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->