Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lacatoire merged 1 commit into from
Aug 25, 2026
+221 −15
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 120 additions & 8 deletions reference/filter/functions/filter-input-array.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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=user@example.com&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) "user@example.com"
["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>
Expand Down
108 changes: 101 additions & 7 deletions reference/filter/functions/filter-var-array.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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>
Expand All @@ -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
Expand Down Expand Up @@ -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>
Expand Down