1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.extract" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>extract</refname>
<refpurpose>Import variables into the current symbol table from an array</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>extract</methodname>
<methodparam><type>array</type><parameter role="reference">array</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>EXTR_OVERWRITE</constant></initializer></methodparam>
<methodparam choice="opt"><type>string</type><parameter>prefix</parameter><initializer>""</initializer></methodparam>
</methodsynopsis>
<para>
Import variables from an array into the current
<link linkend="features.gc.refcounting-basics">symbol table</link>.
</para>
<para>
Checks each key to see whether it has a valid variable name.
It also checks for collisions with existing variables in
the symbol table.
</para>
<warning>
<para>
Do not use <function>extract</function> on untrusted data, like user input
(e.g. <varname>$_GET</varname>, <varname>$_FILES</varname>).
</para>
</warning>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>array</parameter></term>
<listitem>
<para>
An associative array. This function treats keys as variable names and
values as variable values. For each key/value pair it will create a
variable in the current symbol table, subject to
<parameter>flags</parameter> and <parameter>prefix</parameter> parameters.
</para>
<para>
You must use an associative array; a numerically indexed array
will not produce results unless you use <constant>EXTR_PREFIX_ALL</constant> or
<constant>EXTR_PREFIX_INVALID</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
The way invalid/numeric keys and collisions are treated is determined
by the extraction <parameter>flags</parameter>. It can be one of the
following values:
<variablelist>
<varlistentry>
<term><constant>EXTR_OVERWRITE</constant></term>
<listitem>
<simpara>
If there is a collision, overwrite the existing variable.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_SKIP</constant></term>
<listitem>
<simpara>
If there is a collision, don't overwrite the existing
variable.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_SAME</constant></term>
<listitem>
<simpara>If there is a collision, prefix the variable name with
<parameter>prefix</parameter>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_ALL</constant></term>
<listitem>
<simpara>
Prefix all variable names with
<parameter>prefix</parameter>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_INVALID</constant></term>
<listitem>
<simpara>
Only prefix invalid/numeric variable names with
<parameter>prefix</parameter>.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_IF_EXISTS</constant></term>
<listitem>
<simpara>
Only overwrite the variable if it already exists in the
current symbol table, otherwise do nothing. This is useful
for defining a list of valid variables and then extracting
only those variables you have defined out of
<varname>$_REQUEST</varname>, for example.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_PREFIX_IF_EXISTS</constant></term>
<listitem>
<simpara>
Only create prefixed variable names if the non-prefixed version
of the same variable exists in the current symbol table.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EXTR_REFS</constant></term>
<listitem>
<simpara>
Extracts variables as references. This effectively means that the
values of the imported variables are still referencing the values of
the <parameter>array</parameter> parameter. You can use this flag
on its own or combine it with any other flag by OR'ing the
<parameter>flags</parameter>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
If <parameter>flags</parameter> is not specified, it is
assumed to be <constant>EXTR_OVERWRITE</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>prefix</parameter></term>
<listitem>
<para>
Note that <parameter>prefix</parameter> is only required if
<parameter>flags</parameter> is <constant>EXTR_PREFIX_SAME</constant>,
<constant>EXTR_PREFIX_ALL</constant>, <constant>EXTR_PREFIX_INVALID</constant>
or <constant>EXTR_PREFIX_IF_EXISTS</constant>. If
the prefixed result is not a valid variable name, it is not
imported into the symbol table. Prefixes are automatically separated from
the array key by an underscore character.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the number of variables successfully imported into the symbol
table.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>extract</function> example</title>
<para>
A possible use for <function>extract</function> is to import into the
symbol table variables contained in an associative array returned by
<function>wddx_deserialize</function>.
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Suppose that $var_array is an array returned from
wddx_deserialize */
$size = "large";
$var_array = array(
"color" => "blue",
"size" => "medium",
"shape" => "sphere"
);
extract($var_array, EXTR_PREFIX_SAME, "wddx");
echo "$color, $size, $shape, $wddx_size\n";
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
blue, large, sphere, medium
]]>
</screen>
<para>
The <varname>$size</varname> wasn't overwritten because we specified
<constant>EXTR_PREFIX_SAME</constant>, which resulted in
<varname>$wddx_size</varname> being created. If <constant>EXTR_SKIP</constant> was
specified, then <varname>$wddx_size</varname> wouldn't even have been created.
<constant>EXTR_OVERWRITE</constant> would have caused <varname>$size</varname> to have
value "medium", and <constant>EXTR_PREFIX_ALL</constant> would result in new variables
being named <varname>$wddx_color</varname>,
<varname>$wddx_size</varname>, and
<varname>$wddx_shape</varname>.
</para>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<warning>
<para>
Do not use <function>extract</function> on untrusted data, like
user input
(i.e. <varname>$_GET</varname>, <varname>$_FILES</varname>, etc.).
If you do, make sure you use one of the non-overwriting
<parameter>flags</parameter> values such as
<constant>EXTR_SKIP</constant> and be aware that you should extract
in the same order that's defined in
<link linkend="ini.variables-order">variables_order</link> within the
<link linkend="ini">&php.ini;</link>.
</para>
</warning>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>compact</function></member>
<member><function>list</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- 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
-->
|
