File: constants.xml

package info (click to toggle)
php-doc 20241205~git.dfcbb86%2Bdfsg-1
links: PTS, VCS
area: main
in suites: trixie
size: 70,956 kB
sloc: xml: 968,269; php: 23,883; javascript: 671; sh: 177; makefile: 37
file content (1241 lines) | stat: -rw-r--r-- 36,288 bytes
<?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 flags 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>&amp;</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>"true"</literal>,
     <literal>"on"</literal>,
     and <literal>"yes"</literal>.
    </simpara>
    <simpara>
     Returns &false; for <literal>"0"</literal>,
     <literal>"false"</literal>,
     <literal>"off"</literal>,
     <literal>"no"</literal>, and
     <literal>""</literal>.
    </simpara>
    <simpara>
     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> name 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>&lt;</literal></member>
      <member><literal>&gt;</literal></member>
      <member><literal>&amp;</literal></member>
     </simplelist>
     and characters with an ASCII value less than 32.
    </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 remove all characters except
     latin letters (<literal>[a-zA-Z]</literal>),
     digits (<literal>[0-9]</literal>),
     and the special characters
     <literal>!#$%&amp;'*+-=?^_`{|}~@.[]</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 remove all characters except
     latin letters (<literal>[a-zA-Z]</literal>),
     digits (<literal>[0-9]</literal>),
     and the special characters
     <literal>$-_.+!*'(),{}|\\^~[]`&lt;&gt;#%";/?:@&amp;=</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 remove 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 remove 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($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
-->