<!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, PHP 7)</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>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Before PHP 7.1.0, <span class="function"><strong>list()</strong></span> only worked on numerical arrays and assumes
the numerical indices start at 0.
</p>
</p></blockquote>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
In PHP 5, <span class="function"><strong>list()</strong></span> assigns the values starting with the
right-most parameter. In PHP 7, <span class="function"><strong>list()</strong></span> starts with the
left-most parameter.
</p>
<p class="para">
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 is not the case in PHP 5, as it's assigned in the
reverse order.
</p>
<p class="para">
Generally speaking, it is advisable to avoid relying on a specific order
of operation, as this may change again in the future.
</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>
</div>
<div class="refsect1 parameters" id="refsect1-function.list-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<code class="parameter">var1</code></dt>
<dd>
<p class="para">
A variable.
</p>
</dd>
</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 changelog" id="refsect1-function.list-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>7.1.0</td>
<td>
It is now possible to specify keys in <span class="function"><strong>list()</strong></span>. This
enables destructuring of arrays with non-integer or non-sequential keys.
</td>
</tr>
<tr>
<td>7.0.0</td>
<td>
<a href="migration70.incompatible.html#migration70.incompatible.variable-handling.list.order" class="link">
The order that the assignment operations are performed in has
changed.
</a>
</td>
</tr>
<tr>
<td>7.0.0</td>
<td>
<a href="migration70.incompatible.html#migration70.incompatible.variable-handling.list.empty" class="link">
<span class="function"><strong>list()</strong></span> expressions can no longer be completely
empty.
</a>
</td>
</tr>
<tr>
<td>7.0.0</td>
<td>
<a href="migration70.incompatible.html#migration70.incompatible.variable-handling.list.string" class="link">
Strings can no longer be unpacked.
</a>
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.list-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-6235">
<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-6236">
<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-6237">
<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-6238">
<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"><p>Output of the above example in PHP 7:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
array(3) {
[0]=>
string(6) "coffee"
[1]=>
string(5) "brown"
[2]=>
string(8) "caffeine"
}
</pre></div>
</div>
<div class="example-contents"><p>Output of the above example in PHP 5:</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>
<p class="para">
<div class="example" id="example-6239">
<p><strong>Example #5 <span class="function"><strong>list()</strong></span> and order of index definitions</strong></p>
<div class="example-contents"><p>
The order in which the indices of the array to be consumed by
<span class="function"><strong>list()</strong></span> are defined is irrelevant.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$foo </span><span style="color: #007700">= array(</span><span style="color: #0000BB">2 </span><span style="color: #007700">=> </span><span style="color: #DD0000">'a'</span><span style="color: #007700">, </span><span style="color: #DD0000">'foo' </span><span style="color: #007700">=> </span><span style="color: #DD0000">'b'</span><span style="color: #007700">, </span><span style="color: #0000BB">0 </span><span style="color: #007700">=> </span><span style="color: #DD0000">'c'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$foo</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">] = </span><span style="color: #DD0000">'d'</span><span style="color: #007700">;<br />list(</span><span style="color: #0000BB">$x</span><span style="color: #007700">, </span><span style="color: #0000BB">$y</span><span style="color: #007700">, </span><span style="color: #0000BB">$z</span><span style="color: #007700">) = </span><span style="color: #0000BB">$foo</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$foo</span><span style="color: #007700">, </span><span style="color: #0000BB">$x</span><span style="color: #007700">, </span><span style="color: #0000BB">$y</span><span style="color: #007700">, </span><span style="color: #0000BB">$z</span><span style="color: #007700">);</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(4) {
[2]=>
string(1) "a"
["foo"]=>
string(1) "b"
[0]=>
string(1) "c"
[1]=>
string(1) "d"
}
string(1) "c"
string(1) "d"
string(1) "a"
</pre></div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-6240">
<p><strong>Example #6 <span class="function"><strong>list()</strong></span> with keys</strong></p>
<div class="example-contents"><p>
As of PHP 7.1.0 <span class="function"><strong>list()</strong></span> can now also contain
explicit keys, which can be given as arbitrary expressions.
Mixing of integer and string keys is allowed; however, elements
with and without keys cannot be mixed.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$data </span><span style="color: #007700">= [<br /> [</span><span style="color: #DD0000">"id" </span><span style="color: #007700">=> </span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">'Tom'</span><span style="color: #007700">],<br /> [</span><span style="color: #DD0000">"id" </span><span style="color: #007700">=> </span><span style="color: #0000BB">2</span><span style="color: #007700">, </span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #DD0000">'Fred'</span><span style="color: #007700">],<br />];<br />foreach (</span><span style="color: #0000BB">$data </span><span style="color: #007700">as [</span><span style="color: #DD0000">"id" </span><span style="color: #007700">=> </span><span style="color: #0000BB">$id</span><span style="color: #007700">, </span><span style="color: #DD0000">"name" </span><span style="color: #007700">=> </span><span style="color: #0000BB">$name</span><span style="color: #007700">]) {<br /> echo </span><span style="color: #DD0000">"id: </span><span style="color: #0000BB">$id</span><span style="color: #DD0000">, name: </span><span style="color: #0000BB">$name</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;<br />}<br />echo </span><span style="color: #0000BB">PHP_EOL</span><span style="color: #007700">;<br />list(</span><span style="color: #0000BB">1 </span><span style="color: #007700">=> </span><span style="color: #0000BB">$second</span><span style="color: #007700">, </span><span style="color: #0000BB">3 </span><span style="color: #007700">=> </span><span style="color: #0000BB">$fourth</span><span style="color: #007700">) = [</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">2</span><span style="color: #007700">, </span><span style="color: #0000BB">3</span><span style="color: #007700">, </span><span style="color: #0000BB">4</span><span style="color: #007700">];<br />echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$second</span><span style="color: #DD0000">, </span><span style="color: #0000BB">$fourth</span><span style="color: #DD0000">\n"</span><span style="color: #007700">;</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>
id: 1, name: Tom
id: 2, name: Fred
2, 4
</pre></div>
</div>
</div>
</p>
</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>
