mirror of
https://github.com/php/doc-en.git
synced 2026-03-23 23:32:18 +01:00
1248 lines
36 KiB
XML
1248 lines
36 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- Generated by xml_proto.php v2.4. Found in /scripts directory of phpdoc. -->
|
|
<appendix xml:id="filter.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
&reftitle.constants;
|
|
&extension.constants;
|
|
|
|
<variablelist>
|
|
<title>Input Constants</title>
|
|
<simpara>
|
|
These constants are used by
|
|
<function>filter_input</function> and
|
|
<function>filter_input_array</function>.
|
|
</simpara>
|
|
<varlistentry xml:id="constant.input-post">
|
|
<term>
|
|
<constant>INPUT_POST</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.post">POST</link> variables.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-get">
|
|
<term>
|
|
<constant>INPUT_GET</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.get">GET</link> variables.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-cookie">
|
|
<term>
|
|
<constant>INPUT_COOKIE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.cookies">COOKIE</link> variables.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-env">
|
|
<term>
|
|
<constant>INPUT_ENV</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.environment">ENV</link> variables.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-server">
|
|
<term>
|
|
<constant>INPUT_SERVER</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.server">SERVER</link> variables.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-session">
|
|
<term>
|
|
<constant>INPUT_SESSION</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.session">SESSION</link> variables.
|
|
(Removed as of PHP 8.0.0; was not implemented previously)
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.input-request">
|
|
<term>
|
|
<constant>INPUT_REQUEST</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="reserved.variables.request">REQUEST</link> variables.
|
|
(Removed as of PHP 8.0.0; was not implemented previously)
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist xml:id="filter.constants.flags.generic">
|
|
<title>Generic Filter Flags</title>
|
|
<varlistentry xml:id="constant.filter-flag-none">
|
|
<term>
|
|
<constant>FILTER_FLAG_NONE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
No flags.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-require-scalar">
|
|
<term>
|
|
<constant>FILTER_REQUIRE_SCALAR</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Flag used to require the input of the filter to be a scalar.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-require-array">
|
|
<term>
|
|
<constant>FILTER_REQUIRE_ARRAY</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Flag used to require the input of the filter to be an <type>array</type>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-force-array">
|
|
<term>
|
|
<constant>FILTER_FORCE_ARRAY</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
This flag wraps scalar inputs into a one element <type>array</type>
|
|
for filters which operate on arrays.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-null-on-failure">
|
|
<term>
|
|
<constant>FILTER_NULL_ON_FAILURE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Use &null; instead of &false; on failure.
|
|
</simpara>
|
|
<simpara>
|
|
Usable with any validation
|
|
<constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
|
|
filter.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist xml:id="filter.constants.flags.sanitization">
|
|
<title>Sanitization Filter Flags</title>
|
|
<varlistentry xml:id="constant.filter-flag-strip-low">
|
|
<term>
|
|
<constant>FILTER_FLAG_STRIP_LOW</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Strip characters with ASCII value less than 32.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-strip-high">
|
|
<term>
|
|
<constant>FILTER_FLAG_STRIP_HIGH</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Strip characters with ASCII value greater than 127.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-strip-backtick">
|
|
<term>
|
|
<constant>FILTER_FLAG_STRIP_BACKTICK</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Strips backtick (<literal>`</literal>) characters.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-encode-low">
|
|
<term>
|
|
<constant>FILTER_FLAG_ENCODE_LOW</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Encode characters with ASCII value less than 32.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-encode-high">
|
|
<term>
|
|
<constant>FILTER_FLAG_ENCODE_HIGH</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Encode characters with ASCII value greater than 127.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-encode-amp">
|
|
<term>
|
|
<constant>FILTER_FLAG_ENCODE_AMP</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Encode <literal>&</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-no-encode-quotes">
|
|
<term>
|
|
<constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Singe and double quotes (<literal>'</literal> and <literal>"</literal>)
|
|
will not be encoded.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-empty-string-null">
|
|
<term>
|
|
<constant>FILTER_FLAG_EMPTY_STRING_NULL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<!-- TODO Document/check which filters accept this flag (FILTER_UNSAFE_RAW and FILTER_SANITIZE_STRING only) -->
|
|
If sanitizing a string results in an empty string,
|
|
convert the value to &null;
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist xml:id="filter.constants.validation">
|
|
<title>Validation Filters</title>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-bool">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_BOOL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Returns &true; for <literal>"1"</literal>,
|
|
<literal>1</literal> including binary, octal and hexadecimal notations, <literal>1.0</literal>,
|
|
<literal>"true"</literal>, <literal>true</literal>,
|
|
<literal>"on"</literal>,
|
|
and <literal>"yes"</literal>.
|
|
</simpara>
|
|
<simpara>
|
|
Returns &false; for <literal>"0"</literal>,
|
|
<literal>0</literal> including binary, octal and hexadecimal notations, <literal>0.0</literal>,
|
|
<literal>"false"</literal>, <literal>false</literal>,
|
|
<literal>"off"</literal>,
|
|
<literal>"no"</literal>, and
|
|
<literal>""</literal>.
|
|
</simpara>
|
|
<simpara>
|
|
String values are compared case-insensitively.
|
|
The return value for non-boolean values depends on the
|
|
<constant>FILTER_NULL_ON_FAILURE</constant>.
|
|
If it is set, &null; is returned, otherwise &false; is returned.
|
|
</simpara>
|
|
<variablelist xml:id="filter.constants.validation.bool.options">
|
|
<title>Available options</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value to return in case the filter fails.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<simpara>
|
|
Available as of PHP 8.0.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-boolean">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_BOOLEAN</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
&Alias; <constant>FILTER_VALIDATE_BOOL</constant>.
|
|
The alias was available prior to the introduction of its canonical
|
|
name in PHP 8.0.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-int">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_INT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Validates whether the value is an integer,
|
|
on success it is converted to type <type>int</type>.
|
|
</simpara>
|
|
|
|
<note>
|
|
<simpara>
|
|
String values are trimmed using <function>trim</function>
|
|
before validation.
|
|
</simpara>
|
|
</note>
|
|
|
|
<variablelist xml:id="filter.constants.validation.int.options">
|
|
<title>Available options</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value to return in case the filter fails.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>min_range</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value is only valid if it is greater than or equal to the provided value.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>max_range</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value is only valid if it is less than or equal to the provided value.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.int.flags">
|
|
<title>Optional Flags</title>
|
|
<varlistentry xml:id="constant.filter-flag-allow-octal">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_OCTAL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
<!-- TODO: Check that explicit octal prefix 0o and 0O are allowed -->
|
|
Allow integers in octal notation
|
|
(<literal>0[0-7]+</literal>).
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-allow-hex">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_HEX</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Allow integers in hexadecimal notation
|
|
(<literal>0x[0-9a-fA-F]+</literal>).
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-float">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_FLOAT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Validates whether the value is a float,
|
|
on success it is converted to type <type>float</type>.
|
|
</simpara>
|
|
|
|
<note>
|
|
<simpara>
|
|
String values are trimmed using <function>trim</function>
|
|
before validation.
|
|
</simpara>
|
|
</note>
|
|
|
|
<variablelist xml:id="filter.constants.validation.float.options">
|
|
<title>Available options</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value to return in case the filter fails.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>decimal</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
<!-- TODO -->
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>min_range</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value is only valid if it is greater than or equal to the provided value.
|
|
Available as of PHP 7.4.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>max_range</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value is only valid if it is less than or equal to the provided value.
|
|
Available as of PHP 7.4.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.float.flags">
|
|
<title>Optional Flags</title>
|
|
<varlistentry>
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_THOUSAND</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Accept commas (<literal>,</literal>),
|
|
which usually represent the thousand separator.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-validate-regexp">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_REGEXP</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Validates value against the regular expression provided by the
|
|
<literal>regexp</literal> option.
|
|
</simpara>
|
|
|
|
<variablelist xml:id="filter.constants.validation.regex.options">
|
|
<title>Available options</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value to return in case the filter fails.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>regexp</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
<link linkend="book.pcre">Perl-compatible</link> regular expression.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-url">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_URL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Validates whether the <acronym>URL</acronym> is valid according to
|
|
<link xlink:href="&url.rfc;2396">RFC 2396</link>.
|
|
</simpara>
|
|
<variablelist xml:id="filter.constants.validation.url.options">
|
|
<title>Available options</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value to return in case the filter fails.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.url.flags">
|
|
<title>Optional Flags</title>
|
|
<varlistentry xml:id="constant.filter-flag-scheme-required">
|
|
<term>
|
|
<constant>FILTER_FLAG_SCHEME_REQUIRED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Requires the <acronym>URL</acronym> to contain a scheme part.
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0 and
|
|
<emphasis>REMOVED</emphasis> as of PHP 8.0.0.
|
|
This is because it is always implied by the
|
|
<constant>FILTER_VALIDATE_URL</constant> filter.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-host-required">
|
|
<term>
|
|
<constant>FILTER_FLAG_HOST_REQUIRED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Requires the <acronym>URL</acronym> to contain a host part.
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0 and
|
|
<emphasis>REMOVED</emphasis> as of PHP 8.0.0.
|
|
This is because it is always implied by the
|
|
<constant>FILTER_VALIDATE_URL</constant> filter.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-path-required">
|
|
<term>
|
|
<constant>FILTER_FLAG_PATH_REQUIRED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Requires the <acronym>URL</acronym> to contain a path part.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-query-required">
|
|
<term>
|
|
<constant>FILTER_FLAG_QUERY_REQUIRED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Requires the <acronym>URL</acronym> to contain a query part.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<warning>
|
|
<simpara>
|
|
A valid <acronym>URL</acronym> may not specify the
|
|
<acronym>HTTP</acronym> protocol (<literal>http://</literal>).
|
|
Therefore, further validation may be required to determine if the
|
|
<acronym>URL</acronym> uses an expected protocol,
|
|
e.g. <literal>ssh://</literal> or <literal>mailto:</literal>.
|
|
</simpara>
|
|
</warning>
|
|
<warning>
|
|
<simpara>
|
|
This filter only works on <acronym>ASCII</acronym> <acronym>URL</acronym>s.
|
|
This means that Internationalized Domain Names (IDN) will always be rejected.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-validate-domain">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_DOMAIN</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Validates whether the domain name is valid according to
|
|
<link xlink:href="&url.rfc;952">RFC 952</link>,
|
|
<link xlink:href="&url.rfc;1034">RFC 1034</link>,
|
|
<link xlink:href="&url.rfc;1035">RFC 1035</link>,
|
|
<link xlink:href="&url.rfc;1034">RFC 1123</link>,
|
|
<link xlink:href="&url.rfc;1034">RFC 2732</link>,
|
|
and
|
|
<link xlink:href="&url.rfc;2181">RFC 2181</link>.
|
|
</simpara>
|
|
<variablelist xml:id="filter.constants.validation.domain.options">
|
|
<title>Available options</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value to return in case the filter fails.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.domain.flags">
|
|
<title>Optional Flags</title>
|
|
<varlistentry xml:id="constant.filter-flag-hostname">
|
|
<term>
|
|
<constant>FILTER_FLAG_HOSTNAME</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Require hostnames to start with an alphanumeric character and contain
|
|
only alphanumerics or hyphens.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-validate-email">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_EMAIL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Validates whether the value is a "valid" e-mail address.
|
|
</simpara>
|
|
|
|
<simpara>
|
|
The validation is performed against the <literal>addr-spec</literal>
|
|
syntax in
|
|
<link xlink:href="&url.rfc;822">RFC 822</link>.
|
|
However, comments, whitespace folding, and dotless domain names
|
|
are not supported, and thus will be rejected.
|
|
</simpara>
|
|
|
|
<variablelist xml:id="filter.constants.validation.email.options">
|
|
<title>Available options</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value to return in case the filter fails.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.email.flags">
|
|
<title>Optional Flags</title>
|
|
<varlistentry xml:id="constant.filter-flag-email-unicode">
|
|
<term>
|
|
<constant>FILTER_FLAG_EMAIL_UNICODE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Accepts Unicode characters in the local part.
|
|
Available as of PHP 7.1.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<warning>
|
|
<simpara>
|
|
Email validation is complex and the only true way to confirm an email
|
|
is valid and exists is to send an email to the address.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-ip">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_IP</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Validates value as IP address.
|
|
</para>
|
|
<variablelist xml:id="filter.constants.validation.ip.options">
|
|
<title>Available options</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value to return in case the filter fails.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<variablelist xml:id="filter.constants.validation.ip.flags">
|
|
<title>Optional Flags</title>
|
|
<varlistentry xml:id="constant.filter-flag-ipv4">
|
|
<term>
|
|
<constant>FILTER_FLAG_IPV4</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Allow IPv4 address.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-ipv6">
|
|
<term>
|
|
<constant>FILTER_FLAG_IPV6</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Allow IPv6 address.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-no-res-range">
|
|
<term>
|
|
<constant>FILTER_FLAG_NO_RES_RANGE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Deny reserved addresses.
|
|
</simpara>
|
|
<simpara>
|
|
These are the ranges that are marked as
|
|
<literal>Reserved-By-Protocol</literal> in
|
|
<link xlink:href="&url.rfc;6890">RFC 6890</link>.
|
|
</simpara>
|
|
<para>
|
|
Which for IPv4 corresponds to the following ranges:
|
|
<simplelist type="inline">
|
|
<member><literal>0.0.0.0/8</literal></member>
|
|
<member><literal>169.254.0.0/16</literal></member>
|
|
<member><literal>127.0.0.0/8</literal></member>
|
|
<member><literal>240.0.0.0/4</literal></member>
|
|
</simplelist>.
|
|
</para>
|
|
<para>
|
|
And for IPv6 corresponds to the following ranges:
|
|
<simplelist type="inline">
|
|
<member><literal>::1/128</literal></member>
|
|
<member><literal>::/128</literal></member>
|
|
<member><literal>::FFFF:0:0/96</literal></member>
|
|
<member><literal>FE80::/10</literal></member>
|
|
</simplelist>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-no-priv-range">
|
|
<term>
|
|
<constant>FILTER_FLAG_NO_PRIV_RANGE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Deny private addresses.
|
|
</simpara>
|
|
<para>
|
|
These are IPv4 addresses which are in the following ranges:
|
|
<simplelist type="inline">
|
|
<member><literal>10.0.0.0/8</literal></member>
|
|
<member><literal>172.16.0.0/12</literal></member>
|
|
<member><literal>192.168.0.0/16</literal></member>
|
|
</simplelist>.
|
|
</para>
|
|
<simpara>
|
|
These are IPv6 addresses starting with
|
|
<literal>FD</literal> or <literal>FC</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-global-range">
|
|
<term>
|
|
<constant>FILTER_FLAG_GLOBAL_RANGE</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Only allow global addresses.
|
|
These can be found in
|
|
<link xlink:href="&url.rfc;6890">RFC 6890</link>
|
|
where the <literal>Global</literal> attribute is <literal>True</literal>.
|
|
Available as of PHP 8.2.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-validate-mac">
|
|
<term>
|
|
<constant>FILTER_VALIDATE_MAC</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Validates whether the value is a MAC address.
|
|
</simpara>
|
|
|
|
<variablelist xml:id="filter.constants.validation.mac.options">
|
|
<title>Available options</title>
|
|
<varlistentry>
|
|
<term><literal>default</literal></term>
|
|
<listitem>
|
|
<simpara>
|
|
Value to return in case the filter fails.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist xml:id="filter.constants.sanitization">
|
|
<title>Sanitizing Filters</title>
|
|
<varlistentry xml:id="constant.filter-unsafe-raw">
|
|
<term>
|
|
<constant>FILTER_UNSAFE_RAW</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
This filter does nothing.
|
|
</simpara>
|
|
<simpara>
|
|
However, it can strip or encode special characters if used together with
|
|
the <constant>FILTER_FLAG_STRIP_<replaceable>*</replaceable></constant>
|
|
and <constant>FILTER_FLAG_ENCODE_<replaceable>*</replaceable></constant>
|
|
filter sanitization flags.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-default">
|
|
<term>
|
|
<constant>FILTER_DEFAULT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
&Alias; <constant>FILTER_UNSAFE_RAW</constant>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-string">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_STRING</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
This filter strips tags and HTML-encodes double and single quotes.
|
|
</simpara>
|
|
<simpara>
|
|
Optionally it can strip or encode specified characters if used together with
|
|
the <constant>FILTER_FLAG_STRIP_<replaceable>*</replaceable></constant>
|
|
and <constant>FILTER_FLAG_ENCODE_<replaceable>*</replaceable></constant>
|
|
filter sanitization flags.
|
|
</simpara>
|
|
<simpara>
|
|
The behaviour of encoding quotes can be disabled by using the
|
|
<constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant> filter flag.
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
<emphasis>Deprecated</emphasis> as of PHP 8.1.0,
|
|
use <function>htmlspecialchars</function> instead.
|
|
</simpara>
|
|
</warning>
|
|
<warning>
|
|
<simpara>
|
|
The way this filter strips tags is not equivalent to
|
|
<function>strip_tags</function>.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-stripped">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_STRIPPED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
&Alias; <constant>FILTER_SANITIZE_STRING</constant>.
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
<emphasis>Deprecated</emphasis> as of PHP 8.1.0,
|
|
use <function>htmlspecialchars</function> instead.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-encoded">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_ENCODED</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
This filter URL-encodes a string.
|
|
</simpara>
|
|
<simpara>
|
|
Optionally it can strip or encode specified characters if used together with
|
|
the <constant>FILTER_FLAG_STRIP_<replaceable>*</replaceable></constant>
|
|
and <constant>FILTER_FLAG_ENCODE_<replaceable>*</replaceable></constant>
|
|
filter sanitization flags.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-special-chars">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_SPECIAL_CHARS</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This filter HTML-encodes
|
|
<simplelist type="inline">
|
|
<member><literal>'</literal></member>
|
|
<member><literal>"</literal></member>
|
|
<member><literal><</literal></member>
|
|
<member><literal>></literal></member>
|
|
<member><literal>&</literal></member>
|
|
</simplelist>
|
|
and characters with an ASCII value less than 32.
|
|
Unlike the <constant>FILTER_SANITIZE_FULL_SPECIAL_CHARS</constant> filter, the
|
|
<constant>FILTER_SANITIZE_SPECIAL_CHARS</constant> filter ignores the
|
|
<constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant> flag.
|
|
</para>
|
|
<simpara>
|
|
Optionally it can strip specified characters if used together with
|
|
the <constant>FILTER_FLAG_STRIP_<replaceable>*</replaceable></constant>
|
|
filter sanitization flags, and it can encode characters with ASCII value
|
|
greater than 127 using <constant>FILTER_FLAG_ENCODE_HIGH</constant>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-full-special-chars">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_FULL_SPECIAL_CHARS</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
This filter is equivalent to calling <function>htmlspecialchars</function>
|
|
with <constant>ENT_QUOTES</constant> set.
|
|
</simpara>
|
|
<simpara>
|
|
The behaviour of encoding quotes can be disabled by using the
|
|
<constant>FILTER_FLAG_NO_ENCODE_QUOTES</constant> filter flag.
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
Like <function>htmlspecialchars</function>, this filter is aware of the
|
|
<link linkend="ini.default-charset">default_charset</link> INI setting.
|
|
If a sequence of bytes is detected that makes up an invalid character
|
|
in the current character set then the entire string is rejected
|
|
resulting in a empty string being returned.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-email">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_EMAIL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Sanitize the string by removing all characters except
|
|
latin letters (<literal>[a-zA-Z]</literal>),
|
|
digits (<literal>[0-9]</literal>),
|
|
and the special characters
|
|
<literal>!#$%&'*+-=?^_`{|}~@.[]</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-url">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_URL</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Sanitize the string by removing all characters except
|
|
latin letters (<literal>[a-zA-Z]</literal>),
|
|
digits (<literal>[0-9]</literal>),
|
|
and the special characters
|
|
<literal>$-_.+!*'(),{}|\\^~[]`<>#%";/?:@&=</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-number-int">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_NUMBER_INT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Sanitize the string by removing all characters except digits
|
|
(<literal>[0-9]</literal>), plus sign (<literal>+</literal>),
|
|
and minus sign (<literal>-</literal>).
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-sanitize-number-float">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_NUMBER_FLOAT</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Sanitize the string by removing all characters except digits
|
|
(<literal>[0-9]</literal>), plus sign (<literal>+</literal>),
|
|
and minus sign (<literal>-</literal>).
|
|
</simpara>
|
|
|
|
<variablelist xml:id="filter.constants.sanitization.float.flags">
|
|
<title>Optional Flags</title>
|
|
<varlistentry xml:id="constant.filter-flag-allow-fraction">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_FRACTION</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Accept dot (<literal>.</literal>) character,
|
|
which usually represents the separator between the integer and
|
|
fractional parts.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-allow-thousand">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_THOUSAND</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Accept commas (<literal>,</literal>) character,
|
|
which usually represents the thousand separator.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry xml:id="constant.filter-flag-allow-scientific">
|
|
<term>
|
|
<constant>FILTER_FLAG_ALLOW_SCIENTIFIC</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Accept numbers in scientific notation by allowing the
|
|
<literal>e</literal> and <literal>E</literal> characters.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<warning>
|
|
<simpara>
|
|
If the <constant>FILTER_FLAG_ALLOW_FRACTION</constant> flag is not used,
|
|
then the decimal separator is removed, altering the value received.
|
|
</simpara>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$number = '12.34';
|
|
|
|
var_dump(filter_var($number, FILTER_SANITIZE_NUMBER_FLOAT));
|
|
var_dump(filter_var($number, FILTER_SANITIZE_NUMBER_FLOAT, FILTER_FLAG_ALLOW_FRACTION));
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
string(4) "1234"
|
|
string(5) "12.34"
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-sanitize-add-slashes">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_ADD_SLASHES</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
Apply <function>addslashes</function> to the input.
|
|
Available as of PHP 7.3.0.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry xml:id="constant.filter-sanitize-magic-quotes">
|
|
<term>
|
|
<constant>FILTER_SANITIZE_MAGIC_QUOTES</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
&Alias; <constant>FILTER_SANITIZE_ADD_SLASHES</constant>.
|
|
</simpara>
|
|
<warning>
|
|
<simpara>
|
|
<emphasis>DEPRECATED</emphasis> as of PHP 7.3.0 and
|
|
<emphasis>REMOVED</emphasis> as of PHP 8.0.0.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<variablelist>
|
|
<title>User Defined Filter</title>
|
|
<varlistentry xml:id="constant.filter-callback">
|
|
<term>
|
|
<constant>FILTER_CALLBACK</constant>
|
|
(<type>int</type>)
|
|
</term>
|
|
<listitem>
|
|
<simpara>
|
|
This filter delegates the filtering to a user defined function.
|
|
The <type>callable</type> is passed via the
|
|
<parameter>options</parameter> parameter as the value associated to
|
|
the <literal>'options'</literal> key.
|
|
</simpara>
|
|
<para>
|
|
The callback should have the following signature:
|
|
<methodsynopsis>
|
|
<type>mixed</type><methodname><replaceable>callback</replaceable></methodname>
|
|
<methodparam><type>string</type><parameter>value</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<variablelist role="function_parameters">
|
|
<varlistentry>
|
|
<term><parameter>value</parameter></term>
|
|
<listitem>
|
|
<simpara>
|
|
The value that is being filtered.
|
|
</simpara>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<note>
|
|
<simpara>
|
|
The value returned by the callback will be the value returned by
|
|
the invoked filter function.
|
|
</simpara>
|
|
</note>
|
|
<example>
|
|
<title>
|
|
Example of using <constant>FILTER_CALLBACK</constant> to validate
|
|
a login name
|
|
</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
function validate_login(string $value): ?string
|
|
{
|
|
if (strlen($value) >= 5 && ctype_alnum($value)) {
|
|
return $value;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
$login = "val1dL0gin";
|
|
$filtered_login = filter_var($login, FILTER_CALLBACK, ['options' => 'validate_login']);
|
|
var_dump($filtered_login);
|
|
|
|
$login = "f&ke login";
|
|
$filtered_login = filter_var($login, FILTER_CALLBACK, ['options' => 'validate_login']);
|
|
var_dump($filtered_login);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
string(10) "val1dL0gin"
|
|
NULL
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<warning>
|
|
<simpara>
|
|
This filter cannot be used with any other filter flags, e.g.
|
|
<constant>FILTER_NULL_ON_FAILURE</constant>.
|
|
</simpara>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</appendix>
|
|
<!-- 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:"~/.phpdoc/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
|
|
-->
|