language/types/array.xml
c97d8be813dd0189f2a97359795fbe7173792878
c97d8be813dd0189f2a97359795fbe7173792878
...
...
@@ -102,8 +102,8 @@ $array = [
102
102
<listitem>
103
103
<simpara>
104
104
<type>Bool</type>s are cast to <type>int</type>s, too, i.e. the key
105
-
<literal>true</literal> will actually be stored under <literal>1</literal>
106
-
and the key <literal>false</literal> under <literal>0</literal>.
105
+
&true; will actually be stored under <literal>1</literal>
106
+
and the key &false; under <literal>0</literal>.
107
107
</simpara>
108
108
</listitem>
109
109
<listitem>
...
...
@@ -375,9 +375,6 @@ function getArray() {
375
375
}
376
376
377
377
$secondElement = getArray()[1];
378
-
379
-
// or
380
-
list(, $secondElement) = getArray();
381
378
?>
382
379
]]>
383
380
</programlisting>
...
...
@@ -387,7 +384,8 @@ list(, $secondElement) = getArray();
387
384
<para>
388
385
Attempting to access an array key which has not been defined is
389
386
the same as accessing any other undefined variable:
390
-
an <constant>E_NOTICE</constant>-level error message will be
387
+
an <constant>E_WARNING</constant>-level error message
388
+
(<constant>E_NOTICE</constant>-level prior to PHP 8.0.0) will be
391
389
issued, and the result will be &null;.
392
390
</para>
393
391
</note>
...
...
@@ -540,6 +538,139 @@ Array
540
538
</note>
541
539
542
540
</sect3>
541
+
542
+
<sect3 xml:id="language.types.array.syntax.destructuring">
543
+
<title>Array destructuring</title>
544
+
545
+
<para>
546
+
Arrays can be destructured using the <literal>[]</literal> (as of PHP 7.1.0) or
547
+
<function>list</function> language constructs. These
548
+
constructs can be used to destructure an array into distinct variables.
549
+
</para>
550
+
551
+
<informalexample>
552
+
<programlisting role="php">
553
+
<![CDATA[
554
+
<?php
555
+
$source_array = ['foo', 'bar', 'baz'];
556
+
557
+
[$foo, $bar, $baz] = $source_array;
558
+
559
+
echo $foo; // prints "foo"
560
+
echo $bar; // prints "bar"
561
+
echo $baz; // prints "baz"
562
+
?>
563
+
]]>
564
+
</programlisting>
565
+
</informalexample>
566
+
567
+
<para>
568
+
Array destructuring can be used in &foreach; to destructure
569
+
a multi-dimensional array while iterating over it.
570
+
</para>
571
+
572
+
<informalexample>
573
+
<programlisting role="php">
574
+
<![CDATA[
575
+
<?php
576
+
$source_array = [
577
+
[1, 'John'],
578
+
[2, 'Jane'],
579
+
];
580
+
581
+
foreach ($source_array as [$id, $name]) {
582
+
// logic here with $id and $name
583
+
}
584
+
?>
585
+
]]>
586
+
</programlisting>
587
+
</informalexample>
588
+
589
+
<para>
590
+
Array elements will be ignored if the variable is not provided. Array
591
+
destructuring always starts at index <literal>0</literal>.
592
+
</para>
593
+
594
+
<informalexample>
595
+
<programlisting role="php">
596
+
<![CDATA[
597
+
<?php
598
+
$source_array = ['foo', 'bar', 'baz'];
599
+
600
+
// Assign the element at index 2 to the variable $baz
601
+
[, , $baz] = $source_array;
602
+
603
+
echo $baz; // prints "baz"
604
+
?>
605
+
]]>
606
+
</programlisting>
607
+
</informalexample>
608
+
609
+
<para>
610
+
As of PHP 7.1.0, associative arrays can be destructured too. This also
611
+
allows for easier selection of the right element in numerically indexed
612
+
arrays as the index can be explicitly specified.
613
+
</para>
614
+
615
+
<informalexample>
616
+
<programlisting role="php">
617
+
<![CDATA[
618
+
<?php
619
+
$source_array = ['foo' => 1, 'bar' => 2, 'baz' => 3];
620
+
621
+
// Assign the element at index 'baz' to the variable $three
622
+
['baz' => $three] = $source_array;
623
+
624
+
echo $three; // prints 3
625
+
626
+
$source_array = ['foo', 'bar', 'baz'];
627
+
628
+
// Assign the element at index 2 to the variable $baz
629
+
[2 => $baz] = $source_array;
630
+
631
+
echo $baz; // prints "baz"
632
+
?>
633
+
]]>
634
+
</programlisting>
635
+
</informalexample>
636
+
637
+
<para>
638
+
Array destructuring can be used for easy swapping of two variables.
639
+
</para>
640
+
641
+
<informalexample>
642
+
<programlisting role="php">
643
+
<![CDATA[
644
+
<?php
645
+
$a = 1;
646
+
$b = 2;
647
+
648
+
[$b, $a] = [$a, $b];
649
+
650
+
echo $a; // prints 2
651
+
echo $b; // prints 1
652
+
?>
653
+
]]>
654
+
</programlisting>
655
+
</informalexample>
656
+
657
+
<note>
658
+
<para>
659
+
The spread operator (<literal>...</literal>) is not supported in assignments.
660
+
</para>
661
+
</note>
662
+
663
+
<note>
664
+
<para>
665
+
Attempting to access an array key which has not been defined is
666
+
the same as accessing any other undefined variable:
667
+
an <constant>E_WARNING</constant>-level error message
668
+
(<constant>E_NOTICE</constant>-level prior to PHP 8.0.0) will be
669
+
issued, and the result will be &null;.
670
+
</para>
671
+
</note>
672
+
</sect3>
673
+
543
674
</sect2><!-- end syntax -->
544
675
545
676
<sect2 xml:id="language.types.array.useful-funcs">
...
...
@@ -944,7 +1075,7 @@ array(3) {
944
1075
<title>Array unpacking</title>
945
1076
946
1077
<para>
947
-
An array prefixed by <code>...</code> will be expanded in place during the definition of the array.
1078
+
An array prefixed by <code>...</code> will be expanded in place during array definition.
948
1079
Only arrays and objects which implement <interfacename>Traversable</interfacename> can be expanded.
949
1080
Array unpacking with <code>...</code> is available as of PHP 7.4.0.
950
1081
</para>
...
...
@@ -1156,7 +1287,7 @@ Do you like yellow?
1156
1287
<![CDATA[
1157
1288
<?php
1158
1289
foreach ($colors as &$color) {
1159
-
$color = strtoupper($color);
1290
+
$color = mb_strtoupper($color);
1160
1291
}
1161
1292
unset($color); /* ensure that following writes to
1162
1293
$color will not modify the last array element */
1163
1294