<!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>Assign variables as if they were an array</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.ksort.html">ksort</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.natcasesort.html">natcasesort</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.list" class="refentry">
<div class="refnamediv">
<h1 class="refname">list</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">list</span> — <span class="dc-title">Assign variables as if they were an array</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.list-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">array</span> <span class="methodname"><strong>list</strong></span>
( <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$var1</code></span>
[, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$...</code></span>
] )</div>
<p class="para rdfs-comment">
Like <span class="function"><a href="function.array.html" class="function">array()</a></span>, this is not really a function,
but a language construct. <span class="function"><strong>list()</strong></span> is used to
assign a list of variables in one operation.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.list-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">var1</code></em></span>
<dd>
<p class="para">
A variable.
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.list-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns the assigned array.
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.list-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-5019">
<p><strong>Example #1 <span class="function"><strong>list()</strong></span> examples</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$info </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'coffee'</span><span style="color: #007700">, </span><span style="color: #DD0000">'brown'</span><span style="color: #007700">, </span><span style="color: #DD0000">'caffeine'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">// Listing all the variables<br /></span><span style="color: #007700">list(</span><span style="color: #0000BB">$drink</span><span style="color: #007700">, </span><span style="color: #0000BB">$color</span><span style="color: #007700">, </span><span style="color: #0000BB">$power</span><span style="color: #007700">) = </span><span style="color: #0000BB">$info</span><span style="color: #007700">;<br />echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$drink</span><span style="color: #DD0000"> is </span><span style="color: #0000BB">$color</span><span style="color: #DD0000"> and </span><span style="color: #0000BB">$power</span><span style="color: #DD0000"> makes it special.\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">// Listing some of them<br /></span><span style="color: #007700">list(</span><span style="color: #0000BB">$drink</span><span style="color: #007700">, , </span><span style="color: #0000BB">$power</span><span style="color: #007700">) = </span><span style="color: #0000BB">$info</span><span style="color: #007700">;<br />echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$drink</span><span style="color: #DD0000"> has </span><span style="color: #0000BB">$power</span><span style="color: #DD0000">.\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">// Or let's skip to only the third one<br /></span><span style="color: #007700">list( , , </span><span style="color: #0000BB">$power</span><span style="color: #007700">) = </span><span style="color: #0000BB">$info</span><span style="color: #007700">;<br />echo </span><span style="color: #DD0000">"I need </span><span style="color: #0000BB">$power</span><span style="color: #DD0000">!\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #FF8000">// list() doesn't work with strings<br /></span><span style="color: #007700">list(</span><span style="color: #0000BB">$bar</span><span style="color: #007700">) = </span><span style="color: #DD0000">"abcde"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$bar</span><span style="color: #007700">); </span><span style="color: #FF8000">// NULL<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-5020">
<p><strong>Example #2 An example use of <span class="function"><strong>list()</strong></span></strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<table><br /> <tr><br /> <th>Employee name</th><br /> <th>Salary</th><br /> </tr><br /><br /><span style="color: #0000BB"><?php<br />$result </span><span style="color: #007700">= </span><span style="color: #0000BB">$pdo</span><span style="color: #007700">-></span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT id, name, salary FROM employees"</span><span style="color: #007700">);<br />while (list(</span><span style="color: #0000BB">$id</span><span style="color: #007700">, </span><span style="color: #0000BB">$name</span><span style="color: #007700">, </span><span style="color: #0000BB">$salary</span><span style="color: #007700">) = </span><span style="color: #0000BB">$result</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">(</span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">FETCH_NUM</span><span style="color: #007700">)) {<br /> echo </span><span style="color: #DD0000">" <tr>\n" </span><span style="color: #007700">.<br /> </span><span style="color: #DD0000">" <td><a href=\"info.php?id=</span><span style="color: #0000BB">$id</span><span style="color: #DD0000">\"></span><span style="color: #0000BB">$name</span><span style="color: #DD0000"></a></td>\n" </span><span style="color: #007700">.<br /> </span><span style="color: #DD0000">" <td></span><span style="color: #0000BB">$salary</span><span style="color: #DD0000"></td>\n" </span><span style="color: #007700">.<br /> </span><span style="color: #DD0000">" </tr>\n"</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">?><br /></span><br /></table></span>
</code></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-5021">
<p><strong>Example #3 Using nested <span class="function"><strong>list()</strong></span></strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br /></span><span style="color: #007700">list(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, list(</span><span style="color: #0000BB">$b</span><span style="color: #007700">, </span><span style="color: #0000BB">$c</span><span style="color: #007700">)) = array(</span><span style="color: #0000BB">1</span><span style="color: #007700">, array(</span><span style="color: #0000BB">2</span><span style="color: #007700">, </span><span style="color: #0000BB">3</span><span style="color: #007700">));<br /><br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, </span><span style="color: #0000BB">$b</span><span style="color: #007700">, </span><span style="color: #0000BB">$c</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents screen">
<div class="cdata"><pre>
int(1)
int(2)
int(3)
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-5022">
<p><strong>Example #4 Using <span class="function"><strong>list()</strong></span> with array indices</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /><br />$info </span><span style="color: #007700">= array(</span><span style="color: #DD0000">'coffee'</span><span style="color: #007700">, </span><span style="color: #DD0000">'brown'</span><span style="color: #007700">, </span><span style="color: #DD0000">'caffeine'</span><span style="color: #007700">);<br /><br />list(</span><span style="color: #0000BB">$a</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">], </span><span style="color: #0000BB">$a</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">], </span><span style="color: #0000BB">$a</span><span style="color: #007700">[</span><span style="color: #0000BB">2</span><span style="color: #007700">]) = </span><span style="color: #0000BB">$info</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>
Gives the following output (note the order of the elements compared in
which order they were written in the <span class="function"><strong>list()</strong></span> syntax):
</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
array(3) {
[2]=>
string(8) "caffeine"
[1]=>
string(5) "brown"
[0]=>
string(6) "coffee"
}
</pre></div>
</div>
</div>
</p>
</div>
<div class="refsect1 notes" id="refsect1-function.list-notes">
<h3 class="title">Notes</h3>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
<span class="function"><strong>list()</strong></span> assigns the values starting with the right-most
parameter. If you are using plain variables, you don't have to worry
about this. But if you are using arrays with indices you usually expect
the order of the indices in the array the same you wrote in the
<span class="function"><strong>list()</strong></span> from left to right; which it isn't. It's
assigned in the reverse order.
</p>
</div>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
Modification of the array during <span class="function"><strong>list()</strong></span> execution (e.g.
using <em>list($a, $b) = $b</em>) results in undefined behavior.
</p>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
<span class="function"><strong>list()</strong></span> only works on numerical arrays and assumes
the numerical indices start at 0.
</p>
</p></blockquote>
</div>
<div class="refsect1 seealso" id="refsect1-function.list-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.each.html" class="function" rel="rdfs-seeAlso">each()</a> - Return the current key and value pair from an array and advance the array cursor</span></li>
<li class="member"> <span class="function"><a href="function.array.html" class="function" rel="rdfs-seeAlso">array()</a> - Create an array</span></li>
<li class="member"> <span class="function"><a href="function.extract.html" class="function" rel="rdfs-seeAlso">extract()</a> - Import variables into the current symbol table from 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.ksort.html">ksort</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.natcasesort.html">natcasesort</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>
