reference/filter/functions/filter-input-array.xml
53054bf8decc8648cf2e90a493692a161e2371af
53054bf8decc8648cf2e90a493692a161e2371af
...
...
@@ -1,182 +1,77 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xml:id="function.filter-input-array" xmlns="http://docbook.org/ns/docbook">
3
+
<refentry xml:id="function.filter-input-array" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
4
4
<refnamediv>
5
5
<refname>filter_input_array</refname>
6
6
<refpurpose>Gets external variables and optionally filters them</refpurpose>
7
7
</refnamediv>
8
+
8
9
<refsect1 role="description">
9
10
&reftitle.description;
10
11
<methodsynopsis>
11
-
<type>mixed</type><methodname>filter_input_array</methodname>
12
+
<type class="union"><type>array</type><type>false</type><type>null</type></type><methodname>filter_input_array</methodname>
12
13
<methodparam><type>int</type><parameter>type</parameter></methodparam>
13
-
<methodparam choice="opt"><type>mixed</type><parameter>definition</parameter></methodparam>
14
-
<methodparam choice="opt"><type>bool</type><parameter>add_empty</parameter><initializer>true</initializer></methodparam>
14
+
<methodparam choice="opt"><type class="union"><type>array</type><type>int</type></type><parameter>options</parameter><initializer><constant>FILTER_DEFAULT</constant></initializer></methodparam>
15
+
<methodparam choice="opt"><type>bool</type><parameter>add_empty</parameter><initializer>&true;</initializer></methodparam>
15
16
</methodsynopsis>
16
17
<para>
17
18
This function is useful for retrieving many values without
18
19
repetitively calling <function>filter_input</function>.
19
20
</para>
20
21
</refsect1>
22
+
21
23
<refsect1 role="parameters">
22
24
&reftitle.parameters;
23
-
<para>
24
-
<variablelist>
25
-
<varlistentry>
26
-
<term><parameter>type</parameter></term>
27
-
<listitem>
28
-
<para>
29
-
One of <constant>INPUT_GET</constant>, <constant>INPUT_POST</constant>,
30
-
<constant>INPUT_COOKIE</constant>, <constant>INPUT_SERVER</constant>, or
31
-
<constant>INPUT_ENV</constant>.
32
-
</para>
33
-
</listitem>
34
-
</varlistentry>
35
-
<varlistentry>
36
-
<term><parameter>definition</parameter></term>
37
-
<listitem>
38
-
<para>
39
-
An array defining the arguments. A valid key is a <type>string</type>
40
-
containing a variable name and a valid value is either a <link
41
-
linkend="filter.filters">filter type</link>, or an <type>array</type>
42
-
optionally specifying the filter, flags and options. If the value is an
43
-
array, valid keys are <literal>filter</literal> which specifies the
44
-
<link linkend="filter.filters">filter type</link>,
45
-
<literal>flags</literal> which specifies any flags that apply to the
46
-
filter, and <literal>options</literal> which specifies any options that
47
-
apply to the filter. See the example below for a better understanding.
48
-
</para>
49
-
<para>
50
-
This parameter can be also an integer holding a <link
51
-
linkend="filter.constants">filter constant</link>. Then all values in the
52
-
input array are filtered by this filter.
53
-
</para>
54
-
</listitem>
55
-
</varlistentry>
56
-
<varlistentry>
57
-
<term><parameter>add_empty</parameter></term>
58
-
<listitem>
59
-
<para>
60
-
Add missing keys as &null; to the return value.
61
-
</para>
62
-
</listitem>
63
-
</varlistentry>
64
-
</variablelist>
65
-
</para>
25
+
<variablelist>
26
+
<varlistentry>
27
+
<term><parameter>type</parameter></term>
28
+
<listitem>
29
+
<simpara>
30
+
One of the <constant>INPUT_<replaceable>*</replaceable></constant> constants.
31
+
</simpara>
32
+
<warning>
33
+
<simpara>
34
+
The content of the superglobal that is being filtered is the original
35
+
"raw" content provided by the <acronym>SAPI</acronym>,
36
+
prior to any user modification to the superglobal.
37
+
To filter a modified superglobal use
38
+
<function>filter_var_array</function> instead.
39
+
</simpara>
40
+
</warning>
41
+
</listitem>
42
+
</varlistentry>
43
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.filter-var-array')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='options']]]/.)">
44
+
<xi:fallback/>
45
+
</xi:include>
46
+
<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.filter-var-array')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='add_empty']]]/.)">
47
+
<xi:fallback/>
48
+
</xi:include>
49
+
</variablelist>
66
50
</refsect1>
51
+
67
52
<refsect1 role="returnvalues">
68
53
&reftitle.returnvalues;
69
-
<para>
70
-
An array containing the values of the requested variables on success, or &false;
71
-
on failure. An array value will be &false; if the filter fails, or &null; if
72
-
the variable is not set. Or if the flag <constant>FILTER_NULL_ON_FAILURE</constant>
73
-
is used, it returns &false; if the variable is not set and &null; if the filter
74
-
fails.
75
-
</para>
76
-
</refsect1>
77
-
78
-
<refsect1 role="examples">
79
-
&reftitle.examples;
80
-
<para>
81
-
<example>
82
-
<title>A <function>filter_input_array</function> example</title>
83
-
<programlisting role="php">
84
-
<![CDATA[
85
-
<?php
86
-
error_reporting(E_ALL | E_STRICT);
87
-
/* data actually came from POST
88
-
$_POST = array(
89
-
'product_id' => 'libgd<script>',
90
-
'component' => '10',
91
-
'versions' => '2.0.33',
92
-
'testscalar' => array('2', '23', '10', '12'),
93
-
'testarray' => '2',
94
-
);
95
-
*/
96
-
97
-
$args = array(
98
-
'product_id' => FILTER_SANITIZE_ENCODED,
99
-
'component' => array('filter' => FILTER_VALIDATE_INT,
100
-
'flags' => FILTER_REQUIRE_ARRAY,
101
-
'options' => array('min_range' => 1, 'max_range' => 10)
102
-
),
103
-
'versions' => FILTER_SANITIZE_ENCODED,
104
-
'doesnotexist' => FILTER_VALIDATE_INT,
105
-
'testscalar' => array(
106
-
'filter' => FILTER_VALIDATE_INT,
107
-
'flags' => FILTER_REQUIRE_SCALAR,
108
-
),
109
-
'testarray' => array(
110
-
'filter' => FILTER_VALIDATE_INT,
111
-
'flags' => FILTER_REQUIRE_ARRAY,
112
-
)
113
-
114
-
);
115
-
116
-
$myinputs = filter_input_array(INPUT_POST, $args);
117
-
118
-
var_dump($myinputs);
119
-
echo "\n";
120
-
?>
121
-
]]>
122
-
</programlisting>
123
-
&example.outputs;
124
-
<screen>
125
-
<![CDATA[
126
-
array(6) {
127
-
["product_id"]=>
128
-
array(1) {
129
-
[0]=>
130
-
string(17) "libgd%3Cscript%3E"
131
-
}
132
-
["component"]=>
133
-
array(1) {
134
-
[0]=>
135
-
int(10)
136
-
}
137
-
["versions"]=>
138
-
array(1) {
139
-
[0]=>
140
-
string(6) "2.0.33"
141
-
}
142
-
["doesnotexist"]=>
143
-
NULL
144
-
["testscalar"]=>
145
-
bool(false)
146
-
["testarray"]=>
147
-
array(1) {
148
-
[0]=>
149
-
int(2)
150
-
}
151
-
}
152
-
]]>
153
-
</screen>
154
-
</example>
155
-
</para>
156
-
</refsect1>
157
-
158
-
<refsect1 role="changelog">
159
-
&reftitle.changelog;
160
-
<para>
161
-
<informaltable>
162
-
<tgroup cols="2">
163
-
<thead>
164
-
<row>
165
-
<entry>&Version;</entry>
166
-
<entry>&Description;</entry>
167
-
</row>
168
-
</thead>
169
-
<tbody>
170
-
<row>
171
-
<entry>5.4.0</entry>
172
-
<entry>
173
-
Added <parameter>add_empty</parameter> parameter.
174
-
</entry>
175
-
</row>
176
-
</tbody>
177
-
</tgroup>
178
-
</informaltable>
179
-
</para>
54
+
<simpara>
55
+
On success, an &array; containing the values of the requested variables.
56
+
</simpara>
57
+
<simpara>
58
+
On failure, &false; is returned.
59
+
Except if the failure is that the input array designated by
60
+
<parameter>type</parameter> is not populated where &null; is returned
61
+
if the <constant>FILTER_NULL_ON_FAILURE</constant> flag is used.
62
+
</simpara>
63
+
<simpara>
64
+
Missing entries from the input array will be populated into the returned
65
+
&array; if <parameter>add_empty</parameter> is &true;.
66
+
In which case, missing entries will be set to &null;,
67
+
unless the <constant>FILTER_NULL_ON_FAILURE</constant> flag is used,
68
+
in which case it will be &false;.
69
+
</simpara>
70
+
<simpara>
71
+
An entry of the returned &array; will be &false; if the filter fails,
72
+
unless the <constant>FILTER_NULL_ON_FAILURE</constant> flag is used,
73
+
in which case it will be &null;.
74
+
</simpara>
180
75
</refsect1>
181
76
182
77
<refsect1 role="notes">
...
...
@@ -192,17 +87,22 @@ array(6) {
192
87
193
88
<refsect1 role="seealso">
194
89
&reftitle.seealso;
195
-
<para>
196
-
<simplelist>
197
-
<member><function>filter_input</function></member>
198
-
<member><function>filter_var_array</function></member>
199
-
<member><xref linkend="filter.filters" /></member>
200
-
</simplelist>
201
-
</para>
90
+
<simplelist>
91
+
<member><function>filter_input</function></member>
92
+
<member><function>filter_var</function></member>
93
+
<member><function>filter_var_array</function></member>
94
+
<member>
95
+
Validation filters
96
+
<constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
97
+
</member>
98
+
<member>
99
+
Sanitization filters
100
+
<constant>FILTER_SANITIZE_<replaceable>*</replaceable></constant>
101
+
</member>
102
+
</simplelist>
202
103
</refsect1>
203
104
204
105
</refentry>
205
-
206
106
<!-- Keep this comment at the end of the file
207
107
Local variables:
208
108
mode: sgml
209
109