[doc-en] master: Refactor filter constants by splitting into separate files (#5886)
| From: | Jordi Kroon via GitHub | Date: | Sun, 27 Sep 2026 17:51:00 +0000 |
| Subject: | [doc-en] master: Refactor filter constants by splitting into separate files (#5886) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23783@lists.php.net to get a copy of this message | ||
Author: Jordi Kroon (jordikroon)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-09-27T19:50:57+02:00
Commit: https://github.com/php/doc-en/commit/a109099b7deda187b68d43d8a90393620eaeb8e1
Raw diff: https://github.com/php/doc-en/commit/a109099b7deda187b68d43d8a90393620eaeb8e1.diff
Refactor filter constants by splitting into separate files (#5886)
Changed paths:
A reference/filter/constants.callback.xml
A reference/filter/constants.flags.generic.xml
A reference/filter/constants.flags.sanitization.xml
A reference/filter/constants.input.xml
A reference/filter/constants.sanitization.xml
A reference/filter/constants.validation.xml
M reference/filter/constants.xml
Diff:
diff --git a/reference/filter/constants.callback.xml b/reference/filter/constants.callback.xml
new file mode 100644
index 000000000000..bc40a9507f8c
--- /dev/null
+++ b/reference/filter/constants.callback.xml
@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<section xml:id="filter.constants.callback" xmlns="http://docbook.org/ns/docbook">
+ <title>User Defined Filter</title>
+ &extension.constants;
+ <variablelist>
+ <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>
+ <note>
+ <simpara>
+ As of PHP 8.1.25 and 8.2.12, the structural flags
+ <constant>FILTER_REQUIRE_ARRAY</constant>,
+ <constant>FILTER_FORCE_ARRAY</constant> and
+ <constant>FILTER_REQUIRE_SCALAR</constant> apply to this filter, and
+ <constant>FILTER_NULL_ON_FAILURE</constant> changes how such a
+ structural failure is reported. In earlier versions all flags were
+ ignored. Filter specific flags are always ignored, and since the return
+ value of the callback is the result, the callback itself cannot fail: no
+ flag turns a <literal>false</literal> returned by the callback into
+ &null; or an exception.
+ </simpara>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</section>
+<!-- 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
+-->
diff --git a/reference/filter/constants.flags.generic.xml
b/reference/filter/constants.flags.generic.xml
new file mode 100644
index 000000000000..5e66cc207b51
--- /dev/null
+++ b/reference/filter/constants.flags.generic.xml
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<section xml:id="filter.constants.flags.generic" xmlns="http://docbook.org/ns/docbook">
+ <title>Generic Filter Flags</title>
+ &extension.constants;
+ <variablelist>
+ <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>
+ <varlistentry xml:id="constant.filter-throw-on-failure">
+ <term>
+ <constant>FILTER_THROW_ON_FAILURE</constant>
+ (<type>int</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Throws a <exceptionname>Filter\FilterFailedException</exceptionname> when a
+ validation filter fails, instead of returning &false;.
+ </simpara>
+ <simpara>
+ Can be used with any validation
+ <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
+ filter.
+ </simpara>
+ <simpara>
+ Available as of PHP 8.5.0.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</section>
+<!-- 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
+-->
diff --git a/reference/filter/constants.flags.sanitization.xml
b/reference/filter/constants.flags.sanitization.xml
new file mode 100644
index 000000000000..d96f3a0586f9
--- /dev/null
+++ b/reference/filter/constants.flags.sanitization.xml
@@ -0,0 +1,119 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<section xml:id="filter.constants.flags.sanitization" xmlns="http://docbook.org/ns/docbook">
+ <title>Sanitization Filter Flags</title>
+ &extension.constants;
+ <variablelist>
+ <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>
+ Single 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>
+</section>
+<!-- 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
+-->
diff --git a/reference/filter/constants.input.xml b/reference/filter/constants.input.xml
new file mode 100644
index 000000000000..d8d0c6ad240d
--- /dev/null
+++ b/reference/filter/constants.input.xml
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<section xml:id="filter.constants.input" xmlns="http://docbook.org/ns/docbook">
+ <title>Input Constants</title>
+ &extension.constants;
+ <simpara>
+ These constants are used by
+ <function>filter_input</function> and
+ <function>filter_input_array</function>.
+ </simpara>
+ <variablelist>
+ <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>
+</section>
+<!-- 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
+-->
diff --git a/reference/filter/constants.sanitization.xml
b/reference/filter/constants.sanitization.xml
new file mode 100644
index 000000000000..bfee0bdda67e
--- /dev/null
+++ b/reference/filter/constants.sanitization.xml
@@ -0,0 +1,329 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<section xml:id="filter.constants.sanitization" xmlns="http://docbook.org/ns/docbook">
+ <title>Sanitizing Filters</title>
+ &extension.constants;
+ <variablelist>
+ <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 an 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>
+</section>
+<!-- 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
+-->
diff --git a/reference/filter/constants.validation.xml b/reference/filter/constants.validation.xml
new file mode 100644
index 000000000000..f4cc066c8629
--- /dev/null
+++ b/reference/filter/constants.validation.xml
@@ -0,0 +1,653 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<section xml:id="filter.constants.validation" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>Validation Filters</title>
+ &extension.constants;
+ <variablelist>
+ <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> including scientific notation,
+ <literal>"true"</literal>, &true;,
+ <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> including scientific notation,
+ <literal>"false"</literal>, &false;,
+ <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 for most schemes.
+ </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>
+ <warning>
+ <simpara>
+ This filter is very permissive. For any scheme other than
+ <literal>http://</literal> or <literal>https://</literal>, host content
+ will be accepted without any validation, though the presence of a host
+ is still required unless the URL has a scheme of
+ <literal>mailto:</literal>, <literal>news:</literal>, or
+ <literal>file:</literal>. Schemes are not themselves validated and may be
+ accepted despite not corresponding to a known URL scheme, or having some
+ other meaning in PHP (like <link linkend="book.phar">phar://</link>).
The
+ filter also accepts <link
xlink:href="&url.filter.loopback;">loopback</link>
+ addresses that correspond to the current host.
+ </simpara>
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+var_dump(filter_var('javascript://x%0aalert(1)', FILTER_VALIDATE_URL));
+var_dump(filter_var('javascript://?demo', FILTER_VALIDATE_URL));
+var_dump(filter_var('news:?demo', FILTER_VALIDATE_URL));
+var_dump(filter_var('phar://demo', FILTER_VALIDATE_URL));
+var_dump(filter_var('123://demo', FILTER_VALIDATE_URL));
+var_dump(filter_var('-://demo', FILTER_VALIDATE_URL));
+var_dump(filter_var('http://127.0.0.1',
FILTER_VALIDATE_URL));
+var_dump(filter_var('gopher://127.0.0.1', FILTER_VALIDATE_URL));
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+string(25) "javascript://x%0aalert(1)"
+bool(false)
+string(10) "news:?demo"
+string(11) "phar://demo"
+string(10) "123://demo"
+string(8) "-://demo"
+string(16) "http://127.0.0.1"
+string(18) "gopher://127.0.0.1"
+]]>
+ </screen>
+ </informalexample>
+ </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>
+ <simpara>
+ Validates value as IP address.
+ </simpara>
+ <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>
+</section>
+<!-- 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
+-->
diff --git a/reference/filter/constants.xml b/reference/filter/constants.xml
index d56f118b1975..31e45919c739 100644
--- a/reference/filter/constants.xml
+++ b/reference/filter/constants.xml
@@ -1,1301 +1,15 @@
<?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">
+<appendix xml:id="filter.constants" xmlns="http://docbook.org/ns/docbook">
&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>
+ &reference.filter.constants.input;
+ &reference.filter.constants.flags.generic;
+ &reference.filter.constants.flags.sanitization;
+ &reference.filter.constants.validation;
+ &reference.filter.constants.sanitization;
+ &reference.filter.constants.callback;
- <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>
- <varlistentry xml:id="constant.filter-throw-on-failure">
- <term>
- <constant>FILTER_THROW_ON_FAILURE</constant>
- (<type>int</type>)
- </term>
- <listitem>
- <simpara>
- Throws a <exceptionname>Filter\FilterFailedException</exceptionname> when a
- validation filter fails, instead of returning &false;.
- </simpara>
- <simpara>
- Can be used with any validation
- <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
- filter.
- </simpara>
- <simpara>
- Available as of PHP 8.5.0.
- </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>
- Single 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> including scientific notation,
- <literal>"true"</literal>, &true;,
- <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> including scientific notation,
- <literal>"false"</literal>, &false;,
- <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 for most schemes.
- </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>
- <warning>
- <simpara>
- This filter is very permissive. For any scheme other than
- <literal>http://</literal> or <literal>https://</literal>, host content
- will be accepted without any validation, though the presence of a host
- is still required unless the URL has a scheme of
- <literal>mailto:</literal>, <literal>news:</literal>, or
- <literal>file:</literal>. Schemes are not themselves validated and may be
- accepted despite not corresponding to a known URL scheme, or having some
- other meaning in PHP (like <link linkend="book.phar">phar://</link>).
The
- filter also accepts <link
xlink:href="&url.filter.loopback;">loopback</link>
- addresses that correspond to the current host.
- </simpara>
- <informalexample>
- <programlisting role="php">
-<![CDATA[
-<?php
-
-var_dump(filter_var('javascript://x%0aalert(1)', FILTER_VALIDATE_URL));
-var_dump(filter_var('javascript://?demo', FILTER_VALIDATE_URL));
-var_dump(filter_var('news:?demo', FILTER_VALIDATE_URL));
-var_dump(filter_var('phar://demo', FILTER_VALIDATE_URL));
-var_dump(filter_var('123://demo', FILTER_VALIDATE_URL));
-var_dump(filter_var('-://demo', FILTER_VALIDATE_URL));
-var_dump(filter_var('http://127.0.0.1',
FILTER_VALIDATE_URL));
-var_dump(filter_var('gopher://127.0.0.1', FILTER_VALIDATE_URL));
-?>
-]]>
- </programlisting>
- &example.outputs;
- <screen>
-<![CDATA[
-string(25) "javascript://x%0aalert(1)"
-bool(false)
-string(10) "news:?demo"
-string(11) "phar://demo"
-string(10) "123://demo"
-string(8) "-://demo"
-string(16) "http://127.0.0.1"
-string(18) "gopher://127.0.0.1"
-]]>
- </screen>
- </informalexample>
- </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>
- <simpara>
- Validates value as IP address.
- </simpara>
- <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 an 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>
- <note>
- <simpara>
- As of PHP 8.1.25 and 8.2.12, the structural flags
- <constant>FILTER_REQUIRE_ARRAY</constant>,
- <constant>FILTER_FORCE_ARRAY</constant> and
- <constant>FILTER_REQUIRE_SCALAR</constant> apply to this filter, and
- <constant>FILTER_NULL_ON_FAILURE</constant> changes how such a
- structural failure is reported. In earlier versions all flags were
- ignored. Filter specific flags are always ignored, and since the return
- value of the callback is the result, the callback itself cannot fail: no
- flag turns a <literal>false</literal> returned by the callback into
- &null; or an exception.
- </simpara>
- </note>
- </listitem>
- </varlistentry>
- </variablelist>
</appendix>
<!-- Keep this comment at the end of the file
Local variables: