<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<sect1 xml:id="control-structures.foreach" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>foreach</title>
 <?phpdoc print-version-for="foreach"?>
 <para>
  The <literal>foreach</literal> construct provides an easy way to
  iterate over <type>array</type>s and <interfacename>Traversable</interfacename> objects.
  <literal>foreach</literal> will issue an error when used with
  a variable containing a different data type or with an uninitialized variable.
  <informalexample>
   <simpara>
    <literal>foreach</literal> can optionally get the <literal>key</literal> of each element:
   </simpara>
   <programlisting>
<![CDATA[
foreach (iterable_expression as $value) {
    statement_list
}

foreach (iterable_expression as $key => $value) {
    statement_list
}
]]>
   </programlisting>
  </informalexample>
 </para>
 <simpara>
  The first form traverses the iterable given by
  <literal>iterable_expression</literal>. On each iteration, the value of
  the current element is assigned to <literal>$value</literal>.
 </simpara>
 <simpara>
  The second form will additionally assign the current element's key to
  the <literal>$key</literal> variable on each iteration.
 </simpara>
 <simpara>
  Note that <literal>foreach</literal> does not modify the internal array
  pointer, which is used by functions such as <function>current</function>
  and <function>key</function>.
 </simpara>
 <simpara>
  It is possible to
  <link linkend="language.oop5.iterations">customize object iteration</link>.
 </simpara>

 <example>
  <title>Common <literal>foreach</literal> usages</title>
  <programlisting role="php">
<![CDATA[
<?php

/* Example: value only */
$array = [1, 2, 3, 17];

foreach ($array as $value) {
    echo "Current element of \$array: $value.\n";
}

/* Example: key and value */
$array = [
    "one" => 1,
    "two" => 2,
    "three" => 3,
    "seventeen" => 17
];

foreach ($array as $key => $value) {
    echo "Key: $key => Value: $value\n";
}

/* Example: multi-dimensional key-value arrays */
$grid = [];
$grid[0][0] = "a";
$grid[0][1] = "b";
$grid[1][0] = "y";
$grid[1][1] = "z";

foreach ($grid as $y => $row) {
    foreach ($row as $x => $value) {
        echo "Value at position x=$x and y=$y: $value\n";
    }
}

/* Example: dynamic arrays */
foreach (range(1, 5) as $value) {
    echo "$value\n";
}
?>
]]>
  </programlisting>
 </example>
 <note>
  <para>
   <literal>foreach</literal> does not support the ability to
   suppress error messages using the
   <link linkend="language.operators.errorcontrol"><literal>@</literal></link>.
  </para>
 </note>

 <sect2 xml:id="control-structures.foreach.list">
  <title>Unpacking nested arrays</title>
  <?phpdoc print-version-for="foreach.list"?>
  <para>
   It is possible to iterate over an array of arrays and unpack the nested array
   into loop variables by using either
   <link linkend="language.types.array.syntax.destructuring">array destructuring</link>
   via <literal>[]</literal> or by using the <function>list</function> language
   construct as the value.

   <note>
    <simpara>
     Please note that
     <link linkend="language.types.array.syntax.destructuring">array destructuring</link>
     via <literal>[]</literal> is only possible as of PHP 7.1.0
    </simpara>
   </note>
  </para>

  <para>
   <informalexample>
    <simpara>
     In both of the following examples <literal>$a</literal> will be set to
     the first element of the nested array and <literal>$b</literal> will
     contain the second element:
    </simpara>
    <programlisting role="php">
<![CDATA[
<?php
$array = [
    [1, 2],
    [3, 4],
];

foreach ($array as [$a, $b]) {
    echo "A: $a; B: $b\n";
}

foreach ($array as list($a, $b)) {
    echo "A: $a; B: $b\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
A: 1; B: 2
A: 3; B: 4
]]>
    </screen>
   </informalexample>
  </para>

  <para>
   When providing fewer variables than there are elements in the array,
   the remaining elements will be ignored.
   Similarly, elements can be skipped over by using a comma:
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$array = [
    [1, 2, 5],
    [3, 4, 6],
];

foreach ($array as [$a, $b]) {
    // Note that there is no $c here.
    echo "$a $b\n";
}

foreach ($array as [, , $c]) {
    // Skipping over $a and $b
    echo "$c\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
1 2
3 4
5
6
]]>
    </screen>
   </informalexample>
  </para>

  <para>
   A notice will be generated if there aren't enough array elements to fill
   the <function>list</function>:

   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$array = [
    [1, 2],
    [3, 4],
];

foreach ($array as [$a, $b, $c]) {
    echo "A: $a; B: $b; C: $c\n";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Notice: Undefined offset: 2 in example.php on line 7
A: 1; B: 2; C:

Notice: Undefined offset: 2 in example.php on line 7
A: 3; B: 4; C:
]]>
    </screen>
   </informalexample>
  </para>
 </sect2>

 <sect2 xml:id="control-structures.foreach.reference">
  <title>foreach and references</title>
  <para>
   It is possible to directly modify array elements within a loop by preceding
   <literal>$value</literal> with <literal>&amp;</literal>.
   In that case the value will be assigned by
   <link linkend="language.references">reference</link>.
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$arr = [1, 2, 3, 4];
foreach ($arr as &$value) {
    $value = $value * 2;
}
// $arr is now [2, 4, 6, 8]
unset($value); // break the reference with the last element
?>
]]>
    </programlisting>
   </informalexample>
  </para>
  <warning>
   <simpara>
    Reference to a <literal>$value</literal> of the last array element
    remain even after the <literal>foreach</literal> loop. It is recommended
    to destroy these using <function>unset</function>.
    Otherwise, the following behavior will occur:
   </simpara>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
$arr = [1, 2, 3, 4];
foreach ($arr as &$value) {
    $value = $value * 2;
}
// $arr is now [2, 4, 6, 8]

// without an unset($value), $value is still a reference to the last item: $arr[3]

foreach ($arr as $key => $value) {
    // $arr[3] will be updated with each value from $arr...
    echo "{$key} => {$value} ";
    print_r($arr);
}
// ...until ultimately the second-to-last value is copied onto the last value
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
0 => 2 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 2 )
1 => 4 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 4 )
2 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
3 => 6 Array ( [0] => 2, [1] => 4, [2] => 6, [3] => 6 )
]]>
    </screen>
   </informalexample>
  </warning>
  <example>
  <title>Iterate a constant array's values by reference</title>
   <programlisting role="php">
<![CDATA[
<?php
foreach ([1, 2, 3, 4] as &$value) {
    $value = $value * 2;
}
?>
]]>
   </programlisting>
  </example>
 </sect2>

 <sect2 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><link linkend="language.types.array">array</link></member>
   <member><interfacename>Traversable</interfacename></member>
   <member><link linkend="language.types.iterable">iterable</link></member>
   <member><function>list</function></member>
  </simplelist>
 </sect2>

</sect1>

<!-- 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
-->