language/control-structures/foreach.xml
e49940b757b35b8ef26bb64380c231eda7b49fc4
...
...
@@ -2,7 +2,7 @@
2
2
<!-- $Revision$ -->
3
3

4
4
<sect1 xml:id="control-structures.foreach" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
-
<title><literal>foreach</literal></title>
5
+
<title>foreach</title>
6
6
<?phpdoc print-version-for="foreach"?>
7
7
<para>
8
8
The <literal>foreach</literal> construct provides an easy way to
...
...
@@ -13,47 +13,33 @@
13
13
<informalexample>
14
14
<programlisting>
15
15
<![CDATA[
16
-
foreach (array_expression as $value)
16
+
foreach (iterable_expression as $value)
17
17
statement
18
-
foreach (array_expression as $key => $value)
18
+
foreach (iterable_expression as $key => $value)
19
19
statement
20
20
]]>
21
21
</programlisting>
22
22
</informalexample>
23
23
</para>
24
24
<simpara>
25
-
The first form loops over the array given by
26
-
<literal>array_expression</literal>. On each iteration, the value of
27
-
the current element is assigned to <literal>$value</literal> and
28
-
the internal array pointer is advanced by one (so on the next
29
-
iteration, you'll be looking at the next element).
25
+
The first form traverses the iterable given by
26
+
<literal>iterable_expression</literal>. On each iteration, the value of
27
+
the current element is assigned to <literal>$value</literal>.
30
28
</simpara>
31
29
<simpara>
32
30
The second form will additionally assign the current element's key to
33
31
the <literal>$key</literal> variable on each iteration.
34
32
</simpara>
35
33
<simpara>
34
+
Note that <literal>foreach</literal> does not modify the internal array
35
+
pointer, which is used by functions such as <function>current</function>
36
+
and <function>key</function>.
37
+
</simpara>
38
+
<simpara>
36
39
It is possible to
37
40
<link linkend="language.oop5.iterations">customize object iteration</link>.
38
41
</simpara>
39
-
<para>
40
-
<note>
41
-
<para>
42
-
In PHP 5, when <literal>foreach</literal> first starts executing, the
43
-
internal array pointer is automatically reset to the first element of the
44
-
array. This means that you do not need to call <function>reset</function>
45
-
before a <literal>foreach</literal> loop.
46
-
</para>
47
-
<para>
48
-
As <literal>foreach</literal> relies on the internal array pointer in PHP
49
-
5, changing it within the loop may lead to unexpected behavior.
50
-
</para>
51
-
<para>
52
-
In PHP 7, <literal>foreach</literal> does not use the internal array
53
-
pointer.
54
-
</para>
55
-
</note>
56
-
</para>
42
+

57
43
<para>
58
44
In order to be able to directly modify array elements within the loop precede
59
45
<literal>$value</literal> with &amp;. In that case the value will be assigned by
...
...
@@ -110,8 +96,7 @@ foreach ($arr as $key => $value) {
110
96
</informalexample>
111
97
</warning>
112
98
<para>
113
-
Before PHP 5.5.0, referencing <literal>$value</literal> is only possible if the iterated array can be
114
-
referenced (i.e. if it is a variable). The following code works only as of PHP 5.5.0:
99
+
It is possible to iterate a constant array's value by reference:
115
100
<informalexample>
116
101
<programlisting role="php">
117
102
<![CDATA[
...
...
@@ -128,7 +113,8 @@ foreach (array(1, 2, 3, 4) as &$value) {
128
113
<note>
129
114
<para>
130
115
<literal>foreach</literal> does not support the ability to
131
-
suppress error messages using '@'.
116
+
suppress error messages using
117
+
<literal linkend="language.operators.errorcontrol">@</literal>.
132
118
</para>
133
119
</note>
134
120
</para>
...
...
@@ -199,7 +185,7 @@ foreach (array(1, 2, 3, 4, 5) as $v) {
199
185
<?phpdoc print-version-for="foreach.list"?>
200
186

201
187
<para>
202
-
PHP 5.5 added the ability to iterate over an array of arrays and unpack the
188
+
It is possible to iterate over an array of arrays and unpack the
203
189
nested array into loop variables by providing a <function>list</function>
204
190
as the value.
205
191
</para>
...
...
@@ -299,43 +285,6 @@ A: 3; B: 4; C:
299
285
</para>
300
286
</sect2>
301
287

302
-
<sect2 role="changelog">
303
-
&reftitle.changelog;
304
-
<para>
305
-
<informaltable>
306
-
<tgroup cols="2">
307
-
<thead>
308
-
<row>
309
-
<entry>&Version;</entry>
310
-
<entry>&Description;</entry>
311
-
</row>
312
-
</thead>
313
-
<tbody>
314
-
<row>
315
-
<entry>7.0.0</entry>
316
-
<entry>
317
-
<literal>foreach</literal> does not use the internal array pointer anymore.
318
-
</entry>
319
-
</row>
320
-
<row>
321
-
<entry>5.5.0</entry>
322
-
<entry>
323
-
Referencing of <literal>$value</literal> is supported for expressions.
324
-
Formerly, only variables have been supported.
325
-
</entry>
326
-
</row>
327
-
<row>
328
-
<entry>5.5.0</entry>
329
-
<entry>
330
-
Unpacking nested arrays with <function>list</function> is supported.
331
-
</entry>
332
-
</row>
333
-
</tbody>
334
-
</tgroup>
335
-
</informaltable>
336
-
</para>
337
-
</sect2>
338
-

339
288
</sect1>
340
289

341
290
<!-- Keep this comment at the end of the file
342
291