<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Import variables into the current symbol table from an array</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.end.html">end</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.in-array.html">in_array</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.extract" class="refentry">
<div class="refnamediv">
<h1 class="refname">extract</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">extract</span> — <span class="dc-title">Import variables into the current symbol table from an array</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.extract-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">int</span> <span class="methodname"><strong>extract</strong></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter reference">&$array</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$flags</code><span class="initializer"> = EXTR_OVERWRITE</span></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$prefix</code><span class="initializer"> = <strong><code>NULL</code></strong></span></span>
]] )</div>
<p class="para rdfs-comment">
Import variables from an array into the current symbol table.
</p>
<p class="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.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.extract-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">array</code></em></span>
<dd>
<p class="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
<em><code class="parameter">flags</code></em> and <em><code class="parameter">prefix</code></em> parameters.
</p>
<p class="para">
You must use an associative array; a numerically indexed array
will not produce results unless you use <strong><code>EXTR_PREFIX_ALL</code></strong> or
<strong><code>EXTR_PREFIX_INVALID</code></strong>.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">flags</code></em></span>
<dd>
<p class="para">
The way invalid/numeric keys and collisions are treated is determined
by the extraction <em><code class="parameter">flags</code></em>. It can be one of the
following values:
<dl>
<dt>
<span class="term"><strong><code>EXTR_OVERWRITE</code></strong></span>
<dd>
<span class="simpara">
If there is a collision, overwrite the existing variable.
</span>
</dd>
</dt>
<dt>
<span class="term"><strong><code>EXTR_SKIP</code></strong></span>
<dd>
<span class="simpara">
If there is a collision, don't overwrite the existing
variable.
</span>
</dd>
</dt>
<dt>
<span class="term"><strong><code>EXTR_PREFIX_SAME</code></strong></span>
<dd>
<span class="simpara">If there is a collision, prefix the variable name with
<em><code class="parameter">prefix</code></em>.
</span>
</dd>
</dt>
<dt>
<span class="term"><strong><code>EXTR_PREFIX_ALL</code></strong></span>
<dd>
<span class="simpara">
Prefix all variable names with
<em><code class="parameter">prefix</code></em>.
</span>
</dd>
</dt>
<dt>
<span class="term"><strong><code>EXTR_PREFIX_INVALID</code></strong></span>
<dd>
<span class="simpara">
Only prefix invalid/numeric variable names with
<em><code class="parameter">prefix</code></em>.
</span>
</dd>
</dt>
<dt>
<span class="term"><strong><code>EXTR_IF_EXISTS</code></strong></span>
<dd>
<span class="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
<var class="varname"><var class="varname"><a href="reserved.variables.request.html" class="classname">$_REQUEST</a></var></var>, for example.
</span>
</dd>
</dt>
<dt>
<span class="term"><strong><code>EXTR_PREFIX_IF_EXISTS</code></strong></span>
<dd>
<span class="simpara">
Only create prefixed variable names if the non-prefixed version
of the same variable exists in the current symbol table.
</span>
</dd>
</dt>
<dt>
<span class="term"><strong><code>EXTR_REFS</code></strong></span>
<dd>
<span class="simpara">
Extracts variables as references. This effectively means that the
values of the imported variables are still referencing the values of
the <em><code class="parameter">array</code></em> parameter. You can use this flag
on its own or combine it with any other flag by OR'ing the
<em><code class="parameter">flags</code></em>.
</span>
</dd>
</dt>
</dl>
</p>
<p class="para">
If <em><code class="parameter">flags</code></em> is not specified, it is
assumed to be <strong><code>EXTR_OVERWRITE</code></strong>.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">prefix</code></em></span>
<dd>
<p class="para">
Note that <em><code class="parameter">prefix</code></em> is only required if
<em><code class="parameter">flags</code></em> is <strong><code>EXTR_PREFIX_SAME</code></strong>,
<strong><code>EXTR_PREFIX_ALL</code></strong>, <strong><code>EXTR_PREFIX_INVALID</code></strong>
or <strong><code>EXTR_PREFIX_IF_EXISTS</code></strong>. 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.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.extract-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns the number of variables successfully imported into the symbol
table.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.extract-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>4.3.0</td>
<td>
<strong><code>EXTR_REFS</code></strong> was added.
</td>
</tr>
<tr>
<td>4.2.0</td>
<td>
<strong><code>EXTR_IF_EXISTS</code></strong> and <strong><code>EXTR_PREFIX_IF_EXISTS</code></strong>
were added.
</td>
</tr>
<tr>
<td>4.0.5</td>
<td>
This function now returns the number of variables extracted.
<strong><code>EXTR_PREFIX_INVALID</code></strong> was added.
<strong><code>EXTR_PREFIX_ALL</code></strong> includes numeric variables as well.
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.extract-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-5012">
<p><strong>Example #1 <span class="function"><strong>extract()</strong></span> example</strong></p>
<div class="example-contents"><p>
A possible use for <span class="function"><strong>extract()</strong></span> is to import into the
symbol table variables contained in an associative array returned by
<span class="function"><a href="function.wddx-deserialize.html" class="function">wddx_deserialize()</a></span>.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">/* Suppose that $var_array is an array returned from<br /> wddx_deserialize */<br /><br /></span><span style="color: #0000BB">$size </span><span style="color: #007700">= </span><span style="color: #DD0000">"large"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">$var_array </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"color" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"blue"</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"size" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"medium"</span><span style="color: #007700">,<br /> </span><span style="color: #DD0000">"shape" </span><span style="color: #007700">=> </span><span style="color: #DD0000">"sphere"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">extract</span><span style="color: #007700">(</span><span style="color: #0000BB">$var_array</span><span style="color: #007700">, </span><span style="color: #0000BB">EXTR_PREFIX_SAME</span><span style="color: #007700">, </span><span style="color: #DD0000">"wddx"</span><span style="color: #007700">);<br /><br />echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$color</span><span style="color: #DD0000">, </span><span style="color: #0000BB">$size</span><span style="color: #DD0000">, </span><span style="color: #0000BB">$shape</span><span style="color: #DD0000">, </span><span style="color: #0000BB">$wddx_size</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
blue, large, sphere, medium
</pre></div>
</div>
<div class="example-contents"><p>
The <var class="varname"><var class="varname">$size</var></var> wasn't overwritten because we specified
<strong><code>EXTR_PREFIX_SAME</code></strong>, which resulted in
<var class="varname"><var class="varname">$wddx_size</var></var> being created. If <strong><code>EXTR_SKIP</code></strong> was
specified, then <var class="varname"><var class="varname">$wddx_size</var></var> wouldn't even have been created.
<strong><code>EXTR_OVERWRITE</code></strong> would have caused <var class="varname"><var class="varname">$size</var></var> to have
value "medium", and <strong><code>EXTR_PREFIX_ALL</code></strong> would result in new variables
being named <var class="varname"><var class="varname">$wddx_color</var></var>,
<var class="varname"><var class="varname">$wddx_size</var></var>, and
<var class="varname"><var class="varname">$wddx_shape</var></var>.
</p></div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.extract-notes">
<h3 class="title">Notes</h3>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
Do not use <span class="function"><strong>extract()</strong></span> on untrusted data, like
user input
(i.e. <var class="varname"><var class="varname"><a href="reserved.variables.get.html" class="classname">$_GET</a></var></var>, <var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES</a></var></var>, etc.).
If you do, for example if you want to run old code that relies
on <a href="security.globals.html" class="link">register_globals</a>
temporarily, make sure you use one of the non-overwriting
<em><code class="parameter">flags</code></em> values such as
<strong><code>EXTR_SKIP</code></strong> and be aware that you should extract
in the same order that's defined in
<a href="ini.core.html#ini.variables-order" class="link">variables_order</a> within the
<a href="ini.html" class="link"><var class="filename">php.ini</var></a>.
</p>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If you
have <a href="security.globals.html" class="link">register_globals</a>
turned on and you use <span class="function"><strong>extract()</strong></span>
on <var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES</a></var></var> and
specify <strong><code>EXTR_SKIP</code></strong>, you may be surprised at
the results.
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
This is not recommended practice and is only documented here for
completeness. The use
of <a href="security.globals.html" class="link">register_globals</a> is
deprecated and calling <span class="function"><strong>extract()</strong></span> on untrusted
data such as <var class="varname"><var class="varname"><a href="reserved.variables.files.html" class="classname">$_FILES</a></var></var> is, as noted above, a
potential security risk. If you encounter this issue, it means
that you are using at least two poor coding practices.
</p>
</div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #FF8000">/* Suppose that $testfile is the name of a file upload input<br /> and that register_globals is turned on. */<br /><br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$testfile</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">extract</span><span style="color: #007700">(</span><span style="color: #0000BB">$_FILES</span><span style="color: #007700">, </span><span style="color: #0000BB">EXTR_SKIP</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$testfile</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$testfile</span><span style="color: #007700">[</span><span style="color: #DD0000">'tmp_name'</span><span style="color: #007700">]);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<span class="simpara">
You might expect to see something like the following:
</span>
<div class="example-contents screen">
<div class="cdata"><pre>
string(14) "/tmp/phpgCCPX8"
array(5) {
["name"]=>
string(10) "somefile.txt"
["type"]=>
string(24) "application/octet-stream"
["tmp_name"]=>
string(14) "/tmp/phpgCCPX8"
["error"]=>
int(0)
["size"]=>
int(4208)
}
string(14) "/tmp/phpgCCPX8"
</pre></div>
</div>
<span class="simpara">
However, you would instead see something like this:
</span>
<div class="example-contents screen">
<div class="cdata"><pre>
string(14) "/tmp/phpgCCPX8"
string(14) "/tmp/phpgCCPX8"
string(1) "/"
</pre></div>
</div>
<p class="para">
This is due to the fact that
since <a href="security.globals.html" class="link">register_globals</a> is
turned on, <var class="varname"><var class="varname">$testfile</var></var> already exists in the
global scope when <span class="function"><strong>extract()</strong></span> is called. And
since <strong><code>EXTR_SKIP</code></strong> is
specified, <var class="varname"><var class="varname">$testfile</var></var> is not overwritten with
the contents of the <strong><code>$_FILES</code></strong> array
so <var class="varname"><var class="varname">$testfile</var></var> remains a string.
Because <a href="language.types.string.html#language.types.string.substr" class="link">strings may
be accessed using array syntax</a> and the non-numeric string
<em>tmp_name</em> is interpreted
as <em>0</em>, PHP
sees <var class="varname"><var class="varname">$testfile['tmp_name']</var></var>
as <var class="varname"><var class="varname">$testfile[0]</var></var>.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-function.extract-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.compact.html" class="function" rel="rdfs-seeAlso">compact()</a> - Create array containing variables and their values</span></li>
<li class="member"> <span class="function"><a href="function.list.html" class="function" rel="rdfs-seeAlso">list()</a> - Assign variables as if they were an array</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.end.html">end</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.in-array.html">in_array</a></div>
<div class="up"><a href="ref.array.html">Array Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
