language/types/array.xml
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>
...
...
@@ -422,7 +420,7 @@ $arr[] = <replaceable>value</replaceable>;
422
420
// <replaceable>value</replaceable> may be any value of any type</synopsis>
423
421
424
422
<para>
425
-
If <varname>$arr</varname> doesn't exist yet, it will be created, so this is
423
+
If <varname>$arr</varname> doesn't exist yet or is set to &null; or &false;, it will be created, so this is
426
424
also an alternative way to create an <type>array</type>. This practice is
427
425
however discouraged because if <varname>$arr</varname> already contains
428
426
some value (e.g. <type>string</type> from request variable) then this
...
...
@@ -437,6 +435,12 @@ $arr[] = <replaceable>value</replaceable>;
437
435
error. Formerly, the string was silently converted to an array.
438
436
</simpara>
439
437
</note>
438
+
<note>
439
+
<simpara>
440
+
As of PHP 8.1.0, creating a new array from &false; value is deprecated.
441
+
Creating a new array from &null; and undefined values is still allowed.
442
+
</simpara>
443
+
</note>
440
444

441
445
<para>
442
446
To change a certain
...
...
@@ -534,6 +538,139 @@ Array
534
538
</note>
535
539

536
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
+

537
674
</sect2><!-- end syntax -->
538
675
539
676
<sect2 xml:id="language.types.array.useful-funcs">
...
...
@@ -934,6 +1071,100 @@ array(3) {
934
1071
</para>
935
1072
</sect2>
936
1073

1074
+
<sect2 xml:id="language.types.array.unpacking">
1075
+
<title>Array unpacking</title>
1076
+

1077
+
<para>
1078
+
An array prefixed by <code>...</code> will be expanded in place during array definition.
1079
+
Only arrays and objects which implement <interfacename>Traversable</interfacename> can be expanded.
1080
+
Array unpacking with <code>...</code> is available as of PHP 7.4.0.
1081
+
</para>
1082
+

1083
+
<para>
1084
+
It's possible to expand multiple times, and add normal elements before or after the <code>...</code> operator:
1085
+

1086
+
<example>
1087
+
<title>Simple array unpacking</title>
1088
+
<programlisting role="php">
1089
+
<![CDATA[
1090
+
<?php
1091
+
// Using short array syntax.
1092
+
// Also, works with array() syntax.
1093
+
$arr1 = [1, 2, 3];
1094
+
$arr2 = [...$arr1]; //[1, 2, 3]
1095
+
$arr3 = [0, ...$arr1]; //[0, 1, 2, 3]
1096
+
$arr4 = [...$arr1, ...$arr2, 111]; //[1, 2, 3, 1, 2, 3, 111]
1097
+
$arr5 = [...$arr1, ...$arr1]; //[1, 2, 3, 1, 2, 3]
1098
+

1099
+
function getArr() {
1100
+
return ['a', 'b'];
1101
+
}
1102
+
$arr6 = [...getArr(), 'c' => 'd']; //['a', 'b', 'c' => 'd']
1103
+
?>
1104
+
]]>
1105
+
</programlisting>
1106
+
</example>
1107
+
</para>
1108
+

1109
+
<para>
1110
+
Unpacking an array with the <code>...</code> operator follows the semantics of the <function>array_merge</function> function.
1111
+
That is, later string keys overwrite earlier ones and integer keys are renumbered:
1112
+

1113
+
<example>
1114
+
<title>Array unpacking with duplicate key</title>
1115
+
<programlisting role="php">
1116
+
<![CDATA[
1117
+
<?php
1118
+
// string key
1119
+
$arr1 = ["a" => 1];
1120
+
$arr2 = ["a" => 2];
1121
+
$arr3 = ["a" => 0, ...$arr1, ...$arr2];
1122
+
var_dump($arr3); // ["a" => 2]
1123
+

1124
+
// integer key
1125
+
$arr4 = [1, 2, 3];
1126
+
$arr5 = [4, 5, 6];
1127
+
$arr6 = [...$arr4, ...$arr5];
1128
+
var_dump($arr6); // [1, 2, 3, 4, 5, 6]
1129
+
// Which is [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6]
1130
+
// where the original integer keys have not been retained.
1131
+
?>
1132
+
]]>
1133
+
</programlisting>
1134
+
</example>
1135
+
</para>
1136
+

1137
+
<note>
1138
+
<para>
1139
+
Keys that are neither integers nor strings throw a <classname>TypeError</classname>.
1140
+
Such keys can only be generated by a <interfacename>Traversable</interfacename> object.
1141
+
</para>
1142
+
</note>
1143
+
<note>
1144
+
<para>
1145
+
Prior to PHP 8.1, unpacking an array which has a string key is not supported:
1146
+
</para>
1147
+
<informalexample>
1148
+
<programlisting role="php">
1149
+
<![CDATA[
1150
+
<?php
1151
+

1152
+
$arr1 = [1, 2, 3];
1153
+
$arr2 = ['a' => 4];
1154
+
$arr3 = [...$arr1, ...$arr2];
1155
+
// Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5
1156
+

1157
+
$arr4 = [1, 2, 3];
1158
+
$arr5 = [4, 5];
1159
+
$arr6 = [...$arr4, ...$arr5]; // works. [1, 2, 3, 4, 5]
1160
+
?>
1161
+
]]>
1162
+
</programlisting>
1163
+
</informalexample>
1164
+
</note>
1165
+

1166
+
</sect2>
1167
+

937
1168
<sect2 xml:id="language.types.array.examples">
938
1169
<title>Examples</title>
939
1170

...
...
@@ -1056,7 +1287,7 @@ Do you like yellow?
1056
1287
<![CDATA[
1057
1288
<?php
1058
1289
foreach ($colors as &$color) {
1059
-
$color = strtoupper($color);
1290
+
$color = mb_strtoupper($color);
1060
1291
}
1061
1292
unset($color); /* ensure that following writes to
1062
1293
$color will not modify the last array element */
1063
1294