<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.list" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>list</refname>
  <refpurpose>Assign variables as if they were an array</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>array</type><methodname>list</methodname>
   <methodparam><type>mixed</type><parameter>var1</parameter></methodparam>
   <methodparam rep="repeat" choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
  </methodsynopsis>
  <para>
   Like <function>array</function>, this is not really a function,
   but a language construct.  <function>list</function> is used to
   assign a list of variables in one operation.
  </para>
  <note>
   <para>
    Before PHP 7.1.0, <function>list</function> only worked on numerical arrays and assumes
    the numerical indices start at 0.
   </para>
  </note>
  <warning>
   <para>
    In PHP 5, <function>list</function> assigns the values starting with the
    right-most parameter. In PHP 7, <function>list</function> starts with the
    left-most parameter.
   </para>
   <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 <function>list</function>
   from left to right, which is not the case in PHP 5, as it's assigned in the
   reverse order.
   </para>
   <para>
    Generally speaking, it is advisable to avoid relying on a specific order
    of operation, as this may change again in the future.
   </para>
  </warning>
  <warning>
   <para>
    Modification of the array during <function>list</function> execution (e.g.
    using <literal>list($a, $b) = $b</literal>) results in undefined behavior.
   </para>
  </warning>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>var1</parameter></term>
     <listitem>
      <para>
       A variable.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the assigned array.
  </para>
 </refsect1>
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.1.0</entry>
       <entry>
        It is now possible to specify keys in <function>list</function>. This
        enables destructuring of arrays with non-integer or non-sequential keys.
       </entry>
      </row>
      <row>
       <entry>7.0.0</entry>
       <entry>
        <link linkend="migration70.incompatible.variable-handling.list.order">
         The order that the assignment operations are performed in has
         changed.
        </link>
       </entry>
      </row>
      <row>
       <entry>7.0.0</entry>
       <entry>
        <link linkend="migration70.incompatible.variable-handling.list.empty">
         <function>list</function> expressions can no longer be completely
         empty.
        </link>
       </entry>
      </row>
      <row>
       <entry>7.0.0</entry>
       <entry>
        <link linkend="migration70.incompatible.variable-handling.list.string">
         Strings can no longer be unpacked.
        </link>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>list</function> examples</title>
    <programlisting role="php">
<![CDATA[
<?php

$info = array('coffee', 'brown', 'caffeine');

// Listing all the variables
list($drink, $color, $power) = $info;
echo "$drink is $color and $power makes it special.\n";

// Listing some of them
list($drink, , $power) = $info;
echo "$drink has $power.\n";

// Or let's skip to only the third one
list( , , $power) = $info;
echo "I need $power!\n";

// list() doesn't work with strings
list($bar) = "abcde";
var_dump($bar); // NULL
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>An example use of <function>list</function></title>
    <programlisting role="php">
<![CDATA[
<table>
 <tr>
  <th>Employee name</th>
  <th>Salary</th>
 </tr>

<?php
$result = $pdo->query("SELECT id, name, salary FROM employees");
while (list($id, $name, $salary) = $result->fetch(PDO::FETCH_NUM)) {
    echo " <tr>\n" .
          "  <td><a href=\"info.php?id=$id\">$name</a></td>\n" .
          "  <td>$salary</td>\n" .
          " </tr>\n";
}

?>

</table>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Using nested <function>list</function></title>
    <programlisting role="php">
<![CDATA[
<?php

list($a, list($b, $c)) = array(1, array(2, 3));

var_dump($a, $b, $c);

?>
]]>
    </programlisting>
    <screen>
<![CDATA[
int(1)
int(2)
int(3)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Using <function>list</function> with array indices</title>
    <programlisting role="php">
<![CDATA[
<?php

$info = array('coffee', 'brown', 'caffeine');

list($a[0], $a[1], $a[2]) = $info;

var_dump($a);

?>
]]>
    </programlisting>
    <para>
     Gives the following output (note the order of the elements compared in
     which order they were written in the <function>list</function> syntax):
    </para>
    &example.outputs.7;
    <screen>
<![CDATA[
array(3) {
  [0]=>
  string(6) "coffee"
  [1]=>
  string(5) "brown"
  [2]=>
  string(8) "caffeine"
}
]]>
    </screen>
    &example.outputs.5;
    <screen>
<![CDATA[
array(3) {
  [2]=>
  string(8) "caffeine"
  [1]=>
  string(5) "brown"
  [0]=>
  string(6) "coffee"
}
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>list</function> and order of index definitions</title>
    <simpara>
     The order in which the indices of the array to be consumed by
     <function>list</function> are defined is irrelevant.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
$foo = array(2 => 'a', 'foo' => 'b', 0 => 'c');
$foo[1] = 'd';
list($x, $y, $z) = $foo;
var_dump($foo, $x, $y, $z);
]]>
    </programlisting>
    <para>
     Gives the following output (note the order of the elements compared in
     which order they were written in the <function>list</function> syntax):
    </para>
    <screen>
<![CDATA[
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"
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><function>list</function> with keys</title>
    <simpara>
     As of PHP 7.1.0 <function>list</function> 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.
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
$data = [
    ["id" => 1, "name" => 'Tom'],
    ["id" => 2, "name" => 'Fred'],
];
foreach ($data as ["id" => $id, "name" => $name]) {
    echo "id: $id, name: $name\n";
}
echo PHP_EOL;
list(1 => $second, 3 => $fourth) = [1, 2, 3, 4];
echo "$second, $fourth\n";
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
id: 1, name: Tom
id: 2, name: Fred

2, 4
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>each</function></member>
    <member><function>array</function></member>
    <member><function>extract</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
-->