[DOC-CVS] [doc-en] master: Add examples for filter_var_array() and filter_input_array() (#5267)

[email protected] (Louis-Arnaud via GitHub)
Newsgroups php.doc.cvs
Message-ID <[email protected]> 
Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-25T12:06:32+02:00

Commit: https://github.com/php/doc-en/commit/85264ba268a398c4b90c1948839d54ce688dd5cd
Raw diff: https://github.com/php/doc-en/commit/85264ba268a398c4b90c1948839d54ce688dd5cd.diff

Add examples for filter_var_array() and filter_input_array() (#5267)

Changed paths:
  M  reference/filter/functions/filter-input-array.xml
  M  reference/filter/functions/filter-var-array.xml


Diff:

diff --git a/reference/filter/functions/filter-input-array.xml b/reference/filter/functions/filter-input-array.xml
index b7d5f64aecf3..48edf7a795c4 100644
--- a/reference/filter/functions/filter-input-array.xml
+++ b/reference/filter/functions/filter-input-array.xml
@@ -52,24 +52,136 @@
   </simpara>
   <simpara>
    On failure, &false; is returned.
-   Except if the failure is that the input array designated by
-   <parameter>type</parameter> is not populated where &null; is returned
-   if the <constant>FILTER_NULL_ON_FAILURE</constant> flag is used.
+   If the input array designated by <parameter>type</parameter> is not
+   populated, &null; is returned instead.
   </simpara>
   <simpara>
-   Missing entries from the input array will be populated into the returned
-   &array; if <parameter>add_empty</parameter> is &true;.
-   In which case, missing entries will be set to &null;,
-   unless the <constant>FILTER_NULL_ON_FAILURE</constant> flag is used,
-   in which case it will be &false;.
+   Missing entries from the input array are added to the returned &array; as
+   &null; if <parameter>add_empty</parameter> is &true;,
+   and are omitted entirely if it is &false;.
+   Unlike <function>filter_input</function>,
+   the <constant>FILTER_NULL_ON_FAILURE</constant> flag does not change this:
+   a missing entry is always &null;.
   </simpara>
   <simpara>
    An entry of the returned &array; will be &false; if the filter fails,
    unless the <constant>FILTER_NULL_ON_FAILURE</constant> flag is used,
    in which case it will be &null;.
+   With the <constant>FILTER_FORCE_ARRAY</constant> flag,
+   that failure value is wrapped in a one element &array;
+   like any other result.
   </simpara>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title>A <function>filter_input_array</function> example</title>
+   <simpara>
+    This example assumes a GET request to
+    <literal>[email protected]&amp;age=twenty&amp;url=https://example.com</literal>.
+    The <literal>age</literal> entry fails because <literal>twenty</literal> is
+    not an integer; a value outside the
+    <literal>1</literal> to <literal>120</literal> range would fail the same way.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$filters = [
+    'email' => FILTER_VALIDATE_EMAIL,
+    'age'   => [
+        'filter'  => FILTER_VALIDATE_INT,
+        'options' => ['min_range' => 1, 'max_range' => 120],
+    ],
+    'url'   => FILTER_VALIDATE_URL,
+];
+
+$result = filter_input_array(INPUT_GET, $filters);
+
+var_dump($result);
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+array(3) {
+  ["email"]=>
+  string(16) "[email protected]"
+  ["age"]=>
+  bool(false)
+  ["url"]=>
+  string(19) "https://example.com"
+}
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Filtering POST data with <function>filter_input_array</function></title>
+   <simpara>
+    This example assumes a POST request with fields
+    <literal>username=&lt;script&gt;alert&lt;/script&gt;</literal> and
+    <literal>comment=Hello World</literal>.
+    No <literal>missing</literal> field is submitted: because
+    <parameter>add_empty</parameter> defaults to &true;, it is still present in
+    the result, set to &null;.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$filters = [
+    'username' => FILTER_SANITIZE_SPECIAL_CHARS,
+    'comment'  => FILTER_SANITIZE_SPECIAL_CHARS,
+    'missing'  => FILTER_VALIDATE_INT,
+];
+
+$result = filter_input_array(INPUT_POST, $filters);
+
+var_dump($result);
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+array(3) {
+  ["username"]=>
+  string(38) "&#60;script&#62;alert&#60;/script&#62;"
+  ["comment"]=>
+  string(11) "Hello World"
+  ["missing"]=>
+  NULL
+}
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Requesting an input type that is not populated</title>
+   <simpara>
+    This example assumes a GET request.
+    Because the request carried no POST fields,
+    the input array designated by <constant>INPUT_POST</constant> is not
+    populated and &null; is returned instead of an &array;.
+    This applies to every input type:
+    a request with no query string yields &null; for
+    <constant>INPUT_GET</constant> as well.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(filter_input_array(INPUT_POST, ['a' => FILTER_VALIDATE_INT]));
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+NULL
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
  <refsect1 role="notes">
   &reftitle.notes;
   <note>
diff --git a/reference/filter/functions/filter-var-array.xml b/reference/filter/functions/filter-var-array.xml
index 8e866de0f5de..5e99d93a2460 100644
--- a/reference/filter/functions/filter-var-array.xml
+++ b/reference/filter/functions/filter-var-array.xml
@@ -48,7 +48,7 @@
      </simpara>
      <simpara>
       The option array is an associative array where the key corresponds
-      to a key in the data <parameter>array</parameter> and the associated
+      to a key in the input array and the associated
       value is either the filter to apply to this entry,
       or an associative array describing how and which filter should be
       applied to this entry.
@@ -62,7 +62,7 @@
       <constant>FILTER_UNSAFE_RAW</constant>, or
       <constant>FILTER_CALLBACK</constant> constants.
       It can optionally contain the <literal>'flags'</literal> key
-      which specifies and flags that apply to the filter,
+      which specifies any flags that apply to the filter,
       and the <literal>'options'</literal> key which specifies any options
       that apply to the filter.
      </simpara>
@@ -81,17 +81,39 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   An array containing the values of the requested variables on success, or &false;
-   on failure. An array value will be &false; if the filter fails, or &null; if
-   the variable is not set.
-  </para>
+  <simpara>
+   On success, an &array; containing the values of the requested variables.
+  </simpara>
+  <simpara>
+   On failure, &false; is returned.
+  </simpara>
+  <simpara>
+   Missing entries from the input array are added to the returned &array; as
+   &null; if <parameter>add_empty</parameter> is &true;,
+   and are omitted entirely if it is &false;.
+  </simpara>
+  <simpara>
+   An entry of the returned &array; will be &false; if the filter fails,
+   unless the <constant>FILTER_NULL_ON_FAILURE</constant> flag is used,
+   in which case it will be &null;.
+   With the <constant>FILTER_FORCE_ARRAY</constant> flag,
+   that failure value is wrapped in a one element &array;
+   like any other result.
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
    <title>A <function>filter_var_array</function> example</title>
+   <simpara>
+    Entries are filtered as scalars unless
+    <constant>FILTER_REQUIRE_ARRAY</constant> or
+    <constant>FILTER_FORCE_ARRAY</constant> is used.
+    The <constant>FILTER_REQUIRE_SCALAR</constant> flag on
+    <literal>testscalar</literal> below therefore only states that default
+    explicitly.
+   </simpara>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -156,6 +178,78 @@ array(6) {
   ["doesnotexist"]=>
   NULL
 }
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Applying a single filter to all values</title>
+   <simpara>
+    When <parameter>options</parameter> is an &integer;, the same filter
+    is applied to every entry in the array.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$data = [
+    'name'  => '<b>John</b>',
+    'email' => 'john@example<script>.com',
+    'bio'   => 'Developer & writer',
+];
+
+var_dump(filter_var_array($data, FILTER_SANITIZE_SPECIAL_CHARS));
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+array(3) {
+  ["name"]=>
+  string(27) "&#60;b&#62;John&#60;/b&#62;"
+  ["email"]=>
+  string(32) "john@example&#60;script&#62;.com"
+  ["bio"]=>
+  string(22) "Developer &#38; writer"
+}
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Using <constant>FILTER_CALLBACK</constant></title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$data = [
+    'name'  => '  John Doe  ',
+    'city'  => '  New York  ',
+];
+
+$options = [
+    'name' => [
+        'filter'  => FILTER_CALLBACK,
+        'options' => 'trim',
+    ],
+    'city' => [
+        'filter'  => FILTER_CALLBACK,
+        'options' => function ($value) {
+            return strtoupper(trim($value));
+        },
+    ],
+];
+
+var_dump(filter_var_array($data, $options));
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+array(2) {
+  ["name"]=>
+  string(8) "John Doe"
+  ["city"]=>
+  string(8) "NEW YORK"
+}
 ]]>
    </screen>
   </example>
lmpx.com only provides a reader for public news (NNTP) servers. It is not affiliated with the servers or forums shown here and is not responsible for the content of articles, which is written by their respective authors.