language/types/array.xml
e587d0655e426f97b3fcb431453da5030e743b23
...
...
@@ -48,60 +48,64 @@ array(
48
48
is commonly used, as it allows easier addition of new elements at the end.
49
49
</para>
50
50

51
-
<para>
52
-
As of PHP 5.4 you can also use the short array syntax, which replaces
53
-
<literal>array()</literal> with <literal>[]</literal>.
54
-
</para>
51
+
<note>
52
+
<para>
53
+
A short array syntax exists which replaces
54
+
<literal>array()</literal> with <literal>[]</literal>.
55
+
</para>
56
+
</note>
55
57

56
58
<example>
57
59
<title>A simple array</title>
58
60
<programlisting role="php">
59
61
<![CDATA[
60
62
<?php
61
-
$array = array(
63
+
$array1 = array(
62
64
"foo" => "bar",
63
65
"bar" => "foo",
64
66
);
65
67

66
-
// as of PHP 5.4
67
-
$array = [
68
+
// Using the short array syntax
69
+
$array2 = [
68
70
"foo" => "bar",
69
71
"bar" => "foo",
70
72
];
73
+

74
+
var_dump($array1, $array2);
71
75
?>
72
76
]]>
73
77
</programlisting>
74
78
</example>
75
79

76
80
<para>
77
-
The <replaceable>key</replaceable> can either be an <type>integer</type>
81
+
The <replaceable>key</replaceable> can either be an <type>int</type>
78
82
or a <type>string</type>. The <replaceable>value</replaceable> can be
79
83
of any type.
80
84
</para>
81
85

82
-
<para>
86
+
<para xml:id="language.types.array.key-casts">
83
87
Additionally the following <replaceable>key</replaceable> casts will occur:
84
88
<itemizedlist>
85
89
<listitem>
86
90
<simpara>
87
-
<type>String</type>s containing valid <type>integer</type>s will be cast to the
88
-
<type>integer</type> type. E.g. the key <literal>"8"</literal> will actually be
91
+
<type>String</type>s containing valid decimal <type>int</type>s, unless the number is preceded by a <literal>+</literal> sign, will be cast to the
92
+
<type>int</type> type. E.g. the key <literal>"8"</literal> will actually be
89
93
stored under <literal>8</literal>. On the other hand <literal>"08"</literal> will
90
94
not be cast, as it isn't a valid decimal integer.
91
95
</simpara>
92
96
</listitem>
93
97
<listitem>
94
98
<simpara>
95
-
<type>Float</type>s are also cast to <type>integer</type>s, which means that the
99
+
<type>Float</type>s are also cast to <type>int</type>s, which means that the
96
100
fractional part will be truncated. E.g. the key <literal>8.7</literal> will actually
97
101
be stored under <literal>8</literal>.
98
102
</simpara>
99
103
</listitem>
100
104
<listitem>
101
105
<simpara>
102
-
<type>Bool</type>s are cast to <type>integer</type>s, too, i.e. the key
103
-
<literal>true</literal> will actually be stored under <literal>1</literal>
104
-
and the key <literal>false</literal> under <literal>0</literal>.
106
+
<type>Bool</type>s are cast to <type>int</type>s, too, i.e. the key
107
+
&true; will actually be stored under <literal>1</literal>
108
+
and the key &false; under <literal>0</literal>.
105
109
</simpara>
106
110
</listitem>
107
111
<listitem>
...
...
@@ -155,12 +159,12 @@ array(1) {
155
159
</example>
156
160

157
161
<para>
158
-
PHP arrays can contain <type>integer</type> and <type>string</type> keys at the same time
162
+
PHP arrays can contain <type>int</type> and <type>string</type> keys at the same time
159
163
as PHP does not distinguish between indexed and associative arrays.
160
164
</para>
161
165

162
166
<example>
163
-
<title>Mixed <type>integer</type> and <type>string</type> keys</title>
167
+
<title>Mixed <type>int</type> and <type>string</type> keys</title>
164
168
<programlisting role="php">
165
169
<![CDATA[
166
170
<?php
...
...
@@ -193,7 +197,7 @@ array(4) {
193
197

194
198
<para>
195
199
The <replaceable>key</replaceable> is optional. If it is not specified, PHP will
196
-
use the increment of the largest previously used <type>integer</type> key.
200
+
use the increment of the largest previously used <type>int</type> key.
197
201
</para>
198
202

199
203
<example>
...
...
@@ -263,6 +267,108 @@ array(4) {
263
267
was <literal>6</literal>.
264
268
</para>
265
269
</example>
270
+

271
+
<example>
272
+
<title>Complex Type Casting and Overwriting example</title>
273
+
<para>
274
+
This example includes all variations of type casting of keys and overwriting
275
+
of elements.
276
+
</para>
277
+
<programlisting role="php">
278
+
<![CDATA[
279
+
<?php
280
+
$array = array(
281
+
1 => 'a',
282
+
'1' => 'b', // the value "a" will be overwritten by "b"
283
+
1.5 => 'c', // the value "b" will be overwritten by "c"
284
+
-1 => 'd',
285
+
'01' => 'e', // as this is not an integer string it will NOT override the key for 1
286
+
'1.5' => 'f', // as this is not an integer string it will NOT override the key for 1
287
+
true => 'g', // the value "c" will be overwritten by "g"
288
+
false => 'h',
289
+
'' => 'i',
290
+
null => 'j', // the value "i" will be overwritten by "j"
291
+
'k', // value "k" is assigned the key 2. This is because the largest integer key before that was 1
292
+
2 => 'l', // the value "k" will be overwritten by "l"
293
+
);
294
+

295
+
var_dump($array);
296
+
?>
297
+
]]>
298
+
</programlisting>
299
+
&example.outputs;
300
+
<screen>
301
+
<![CDATA[
302
+
array(7) {
303
+
[1]=>
304
+
string(1) "g"
305
+
[-1]=>
306
+
string(1) "d"
307
+
["01"]=>
308
+
string(1) "e"
309
+
["1.5"]=>
310
+
string(1) "f"
311
+
[0]=>
312
+
string(1) "h"
313
+
[""]=>
314
+
string(1) "j"
315
+
[2]=>
316
+
string(1) "l"
317
+
}
318
+
]]>
319
+
</screen>
320
+
</example>
321
+

322
+
<example>
323
+
<title>Negative index example</title>
324
+
<simpara>
325
+
When assigning a negative integer key <literal>n</literal>, PHP will take care to
326
+
assign the next key to <literal>n+1</literal>.
327
+
</simpara>
328
+
<programlisting role="php">
329
+
<![CDATA[
330
+
<?php
331
+
$array = [];
332
+

333
+
$array[-5] = 1;
334
+
$array[] = 2;
335
+

336
+
var_dump($array);
337
+
?>
338
+
]]>
339
+
</programlisting>
340
+
&example.outputs;
341
+
<screen>
342
+
<![CDATA[
343
+
array(2) {
344
+
[-5]=>
345
+
int(1)
346
+
[-4]=>
347
+
int(2)
348
+
}
349
+
]]>
350
+
</screen>
351
+

352
+
<warning>
353
+
<simpara>
354
+
Prior to PHP 8.3.0, assigning a negative integer key <literal>n</literal> would
355
+
assign the next key to <literal>0</literal>, the previous example would
356
+
therefore output:
357
+
</simpara>
358
+
<informalexample>
359
+
<screen>
360
+
<![CDATA[
361
+
array(2) {
362
+
[-5]=>
363
+
int(1)
364
+
[0]=>
365
+
int(2)
366
+
}
367
+
]]>
368
+
</screen>
369
+
</informalexample>
370
+
</warning>
371
+
</example>
266
372
</sect3>
267
373

268
374
<sect3 xml:id="language.types.array.syntax.accessing">
...
...
@@ -305,22 +411,13 @@ string(3) "foo"
305
411

306
412
<note>
307
413
<para>
308
-
Both square brackets and curly braces can be used interchangeably
309
-
for accessing array elements (e.g. <literal>$array[42]</literal> and <literal>$array{42}</literal> will
310
-
both do the same thing in the example above).
414
+
Prior to PHP 8.0.0, square brackets and curly braces could be used interchangeably
415
+
for accessing array elements (e.g. <literal>$array[42]</literal> and <literal>$array{42}</literal>
416
+
would both do the same thing in the example above).
417
+
The curly brace syntax was deprecated as of PHP 7.4.0 and no longer supported as of PHP 8.0.0.
311
418
</para>
312
419
</note>
313
420

314
-
<para>
315
-
As of PHP 5.4 it is possible to array dereference the result of a function
316
-
or method call directly. Before it was only possible using a temporary
317
-
variable.
318
-
</para>
319
-
320
-
<para>
321
-
As of PHP 5.5 it is possible to array dereference an array literal.
322
-
</para>
323
-
324
421
<example>
325
422
<title>Array dereferencing</title>
326
423
<programlisting role="php">
...
...
@@ -330,15 +427,9 @@ function getArray() {
330
427
return array(1, 2, 3);
331
428
}
332
429

333
-
// on PHP 5.4
334
430
$secondElement = getArray()[1];
335
431

336
-
// previously
337
-
$tmp = getArray();
338
-
$secondElement = $tmp[1];
339
-

340
-
// or
341
-
list(, $secondElement) = getArray();
432
+
var_dump($secondElement);
342
433
?>
343
434
]]>
344
435
</programlisting>
...
...
@@ -348,10 +439,19 @@ list(, $secondElement) = getArray();
348
439
<para>
349
440
Attempting to access an array key which has not been defined is
350
441
the same as accessing any other undefined variable:
351
-
an <constant>E_NOTICE</constant>-level error message will be
442
+
an <constant>E_WARNING</constant>-level error message
443
+
(<constant>E_NOTICE</constant>-level prior to PHP 8.0.0) will be
352
444
issued, and the result will be &null;.
353
445
</para>
354
446
</note>
447
+
<note>
448
+
<para>
449
+
Array dereferencing a scalar value which is not a <type>string</type>
450
+
yields &null;. Prior to PHP 7.4.0, that did not issue an error message.
451
+
As of PHP 7.4.0, this issues <constant>E_NOTICE</constant>;
452
+
as of PHP 8.0.0, this issues <constant>E_WARNING</constant>.
453
+
</para>
454
+
</note>
355
455
</sect3>
356
456

357
457
<sect3 xml:id="language.types.array.syntax.modifying">
...
...
@@ -371,19 +471,31 @@ list(, $secondElement) = getArray();
371
471
<synopsis>
372
472
$arr[<replaceable>key</replaceable>] = <replaceable>value</replaceable>;
373
473
$arr[] = <replaceable>value</replaceable>;
374
-
// <replaceable>key</replaceable> may be an <type>integer</type> or <type>string</type>
474
+
// <replaceable>key</replaceable> may be an <type>int</type> or <type>string</type>
375
475
// <replaceable>value</replaceable> may be any value of any type</synopsis>
376
476

377
477
<para>
378
-
If <varname>$arr</varname> doesn't exist yet, it will be created, so this is
478
+
If <varname>$arr</varname> doesn't exist yet or is set to &null; or &false;, it will be created, so this is
379
479
also an alternative way to create an <type>array</type>. This practice is
380
480
however discouraged because if <varname>$arr</varname> already contains
381
481
some value (e.g. <type>string</type> from request variable) then this
382
482
value will stay in the place and <literal>[]</literal> may actually stand
383
483
for <link linkend="language.types.string.substr">string access
384
-
operator</link>. It is always better to initialize variable by a direct
484
+
operator</link>. It is always better to initialize a variable by a direct
385
485
assignment.
386
486
</para>
487
+
<note>
488
+
<simpara>
489
+
As of PHP 7.1.0, applying the empty index operator on a string throws a fatal
490
+
error. Formerly, the string was silently converted to an array.
491
+
</simpara>
492
+
</note>
493
+
<note>
494
+
<simpara>
495
+
As of PHP 8.1.0, creating a new array from &false; value is deprecated.
496
+
Creating a new array from &null; and undefined values is still allowed.
497
+
</simpara>
498
+
</note>
387
499

388
500
<para>
389
501
To change a certain
...
...
@@ -391,7 +503,8 @@ $arr[] = <replaceable>value</replaceable>;
391
503
key/value pair, call the <function>unset</function> function on it.
392
504
</para>
393
505

394
-
<informalexample>
506
+
<example>
507
+
<title>Using Square Brackets with Arrays</title>
395
508
<programlisting role="php">
396
509
<![CDATA[
397
510
<?php
...
...
@@ -405,17 +518,21 @@ $arr["x"] = 42; // This adds a new element to
405
518

406
519
unset($arr[5]); // This removes the element from the array
407
520

521
+
var_dump($arr);
522
+

408
523
unset($arr); // This deletes the whole array
524
+

525
+
var_dump($arr);
409
526
?>
410
527
]]>
411
528
</programlisting>
412
-
</informalexample>
529
+
</example>
413
530

414
531
<note>
415
532
<para>
416
533
As mentioned above, if no key is specified, the maximum of the existing
417
-
<type>integer</type> indices is taken, and the new key will be that maximum
418
-
value plus 1 (but at least 0). If no <type>integer</type> indices exist yet, the key will
534
+
<type>int</type> indices is taken, and the new key will be that maximum
535
+
value plus 1 (but at least 0). If no <type>int</type> indices exist yet, the key will
419
536
be <literal>0</literal> (zero).
420
537
</para>
421
538

...
...
@@ -481,6 +598,144 @@ Array
481
598
</note>
482
599

483
600
</sect3>
601
+

602
+
<sect3 xml:id="language.types.array.syntax.destructuring">
603
+
<title>Array destructuring</title>
604
+

605
+
<para>
606
+
Arrays can be destructured using the <literal>[]</literal> (as of PHP 7.1.0) or
607
+
<function>list</function> language constructs. These
608
+
constructs can be used to destructure an array into distinct variables.
609
+
</para>
610
+

611
+
<example>
612
+
<title>Array Destructuring</title>
613
+
<programlisting role="php">
614
+
<![CDATA[
615
+
<?php
616
+
$source_array = ['foo', 'bar', 'baz'];
617
+

618
+
[$foo, $bar, $baz] = $source_array;
619
+

620
+
echo $foo, PHP_EOL; // prints "foo"
621
+
echo $bar, PHP_EOL; // prints "bar"
622
+
echo $baz, PHP_EOL; // prints "baz"
623
+
?>
624
+
]]>
625
+
</programlisting>
626
+
</example>
627
+

628
+
<para>
629
+
Array destructuring can be used in &foreach; to destructure
630
+
a multi-dimensional array while iterating over it.
631
+
</para>
632
+

633
+
<example>
634
+
<title>Array Destructuring in Foreach</title>
635
+
<programlisting role="php">
636
+
<![CDATA[
637
+
<?php
638
+
$source_array = [
639
+
[1, 'John'],
640
+
[2, 'Jane'],
641
+
];
642
+

643
+
foreach ($source_array as [$id, $name]) {
644
+
echo "{$id}: '{$name}'\n";
645
+
}
646
+
?>
647
+
]]>
648
+
</programlisting>
649
+
</example>
650
+

651
+
<para>
652
+
Array elements will be ignored if the variable is not provided. Array
653
+
destructuring always starts at index <literal>0</literal>.
654
+
</para>
655
+

656
+
<example>
657
+
<title>Ignoring Elements</title>
658
+
<programlisting role="php">
659
+
<![CDATA[
660
+
<?php
661
+
$source_array = ['foo', 'bar', 'baz'];
662
+

663
+
// Assign the element at index 2 to the variable $baz
664
+
[, , $baz] = $source_array;
665
+

666
+
echo $baz; // prints "baz"
667
+
?>
668
+
]]>
669
+
</programlisting>
670
+
</example>
671
+

672
+
<para>
673
+
As of PHP 7.1.0, associative arrays can be destructured too. This also
674
+
allows for easier selection of the right element in numerically indexed
675
+
arrays as the index can be explicitly specified.
676
+
</para>
677
+

678
+
<example>
679
+
<title>Destructuring Associative Arrays</title>
680
+
<programlisting role="php">
681
+
<![CDATA[
682
+
<?php
683
+
$source_array = ['foo' => 1, 'bar' => 2, 'baz' => 3];
684
+

685
+
// Assign the element at index 'baz' to the variable $three
686
+
['baz' => $three] = $source_array;
687
+

688
+
echo $three, PHP_EOL; // prints 3
689
+

690
+
$source_array = ['foo', 'bar', 'baz'];
691
+

692
+
// Assign the element at index 2 to the variable $baz
693
+
[2 => $baz] = $source_array;
694
+

695
+
echo $baz, PHP_EOL; // prints "baz"
696
+
?>
697
+
]]>
698
+
</programlisting>
699
+
</example>
700
+

701
+
<para>
702
+
Array destructuring can be used for easy swapping of two variables.
703
+
</para>
704
+

705
+
<example>
706
+
<title>Swapping Two Variable</title>
707
+
<programlisting role="php">
708
+
<![CDATA[
709
+
<?php
710
+
$a = 1;
711
+
$b = 2;
712
+

713
+
[$b, $a] = [$a, $b];
714
+

715
+
echo $a, PHP_EOL; // prints 2
716
+
echo $b, PHP_EOL; // prints 1
717
+
?>
718
+
]]>
719
+
</programlisting>
720
+
</example>
721
+

722
+
<note>
723
+
<para>
724
+
The spread operator (<literal>...</literal>) is not supported in assignments.
725
+
</para>
726
+
</note>
727
+

728
+
<note>
729
+
<para>
730
+
Attempting to access an array key which has not been defined is
731
+
the same as accessing any other undefined variable:
732
+
an <constant>E_WARNING</constant>-level error message
733
+
(<constant>E_NOTICE</constant>-level prior to PHP 8.0.0) will be
734
+
issued, and the result will be &null;.
735
+
</para>
736
+
</note>
737
+
</sect3>
738
+

484
739
</sect2><!-- end syntax -->
485
740

486
741
<sect2 xml:id="language.types.array.useful-funcs">
...
...
@@ -500,24 +755,28 @@ Array
500
755
<function>array_values</function> function.
501
756
</para>
502
757

503
-
<informalexample>
758
+
<example>
759
+
<title>Unsetting Intermediate Elements</title>
504
760
<programlisting role="php">
505
761
<![CDATA[
506
762
<?php
507
763
$a = array(1 => 'one', 2 => 'two', 3 => 'three');
508
-
unset($a[2]);
764
+

509
765
/* will produce an array that would have been defined as
510
766
$a = array(1 => 'one', 3 => 'three');
511
767
and NOT
512
768
$a = array(1 => 'one', 2 =>'three');
513
769
*/
770
+
unset($a[2]);
771
+
var_dump($a);
514
772

515
773
$b = array_values($a);
516
774
// Now $b is array(0 => 'one', 1 =>'three')
775
+
var_dump($b);
517
776
?>
518
777
]]>
519
778
</programlisting>
520
-
</informalexample>
779
+
</example>
521
780
</note>
522
781

523
782
<para>
...
...
@@ -554,34 +813,45 @@ echo $foo[bar];
554
813

555
814
<para>
556
815
This is wrong, but it works. The reason is that this code has an undefined
557
-
constant (bar) rather than a <type>string</type> ('bar' - notice the
558
-
quotes). PHP may in the future define constants which, unfortunately for such
559
-
code, have the same name. It works because PHP automatically converts a
816
+
constant (<literal>bar</literal>) rather than a <type>string</type> (<literal>'bar'</literal> - notice the
817
+
quotes). It works because PHP automatically converts a
560
818
<emphasis>bare string</emphasis> (an unquoted <type>string</type> which does
561
819
not correspond to any known symbol) into a <type>string</type> which
562
820
contains the bare <type>string</type>. For instance, if there is no defined
563
821
constant named <constant>bar</constant>, then PHP will substitute in the
564
822
<type>string</type> <literal>'bar'</literal> and use that.
565
823
</para>
566
-

567
-
<note>
824
+
<warning>
568
825
<simpara>
569
-
This does not mean to <emphasis>always</emphasis> quote the key. Do not
570
-
quote keys which are <link linkend="language.constants">constants</link> or
571
-
<link linkend="language.variables">variables</link>, as this will prevent
572
-
PHP from interpreting them.
826
+
The fallback to treat an undefined constant as bare string issues an error
827
+
of level <constant>E_NOTICE</constant>.
828
+
This has been deprecated as of PHP 7.2.0, and issues an error
829
+
of level <constant>E_WARNING</constant>.
830
+
As of PHP 8.0.0, it has been removed and throws an
831
+
<classname>Error</classname> exception.
573
832
</simpara>
833
+
</warning>
574
834

575
-
<informalexample>
576
-
<programlisting role="php">
835
+
<simpara>
836
+
This does not mean to <emphasis>always</emphasis> quote the key. Do not
837
+
quote keys which are <link linkend="language.constants">constants</link> or
838
+
<link linkend="language.variables">variables</link>, as this will prevent
839
+
PHP from interpreting them.
840
+
</simpara>
841
+

842
+
<example>
843
+
<title>Key Quoting</title>
844
+
<programlisting role="php">
577
845
<![CDATA[
578
846
<?php
579
847
error_reporting(E_ALL);
580
848
ini_set('display_errors', true);
581
849
ini_set('html_errors', false);
850
+

582
851
// Simple array:
583
852
$array = array(1, 2);
584
853
$count = count($array);
854
+

585
855
for ($i = 0; $i < $count; $i++) {
586
856
echo "\nChecking $i: \n";
587
857
echo "Bad: " . $array['$i'] . "\n";
...
...
@@ -592,7 +862,7 @@ for ($i = 0; $i < $count; $i++) {
592
862
?>
593
863
]]>
594
864
</programlisting>
595
-
</informalexample>
865
+
</example>
596
866
&example.outputs;
597
867
<screen>
598
868
<![CDATA[
...
...
@@ -612,14 +882,14 @@ Notice: Undefined index: $i in /path/to/script.html on line 11
612
882
Bad:
613
883
Good: 2
614
884
]]>
615
-
</screen>
616
-
</note>
885
+
</screen>
617
886

618
887
<para>
619
888
More examples to demonstrate this behaviour:
620
889
</para>
621
890

622
-
<informalexample>
891
+
<example>
892
+
<title>More Examples</title>
623
893
<programlisting role="php">
624
894
<![CDATA[
625
895
<?php
...
...
@@ -629,40 +899,52 @@ error_reporting(E_ALL);
629
899
$arr = array('fruit' => 'apple', 'veggie' => 'carrot');
630
900

631
901
// Correct
632
-
print $arr['fruit']; // apple
633
-
print $arr['veggie']; // carrot
902
+
echo $arr['fruit'], PHP_EOL; // apple
903
+
echo $arr['veggie'], PHP_EOL; // carrot
634
904

635
-
// Incorrect. This works but also throws a PHP error of level E_NOTICE because
905
+
// Incorrect. This works but also throws a PHP Error because
636
906
// of an undefined constant named fruit
637
907
//
638
-
// Notice: Use of undefined constant fruit - assumed 'fruit' in...
639
-
print $arr[fruit]; // apple
908
+
// Error: Undefined constant "fruit"
909
+
try {
910
+
echo $arr[fruit]; // apple
911
+
} catch (Error $e) {
912
+
echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
913
+
}
640
914

641
915
// This defines a constant to demonstrate what's going on. The value 'veggie'
642
916
// is assigned to a constant named fruit.
643
917
define('fruit', 'veggie');
644
918

645
919
// Notice the difference now
646
-
print $arr['fruit']; // apple
647
-
print $arr[fruit]; // carrot
920
+
echo $arr['fruit'], PHP_EOL; // apple
921
+
echo $arr[fruit], PHP_EOL; // carrot
648
922

649
923
// The following is okay, as it's inside a string. Constants are not looked for
650
924
// within strings, so no E_NOTICE occurs here
651
-
print "Hello $arr[fruit]"; // Hello apple
925
+
echo "Hello $arr[fruit]", PHP_EOL; // Hello apple
652
926

653
927
// With one exception: braces surrounding arrays within strings allows constants
654
928
// to be interpreted
655
-
print "Hello {$arr[fruit]}"; // Hello carrot
656
-
print "Hello {$arr['fruit']}"; // Hello apple
929
+
echo "Hello {$arr[fruit]}", PHP_EOL; // Hello carrot
930
+
echo "Hello {$arr['fruit']}", PHP_EOL; // Hello apple
657
931

932
+
// Concatenation is another option
933
+
echo "Hello " . $arr['fruit'], PHP_EOL; // Hello apple
934
+
?>
935
+
]]>
936
+
</programlisting>
937
+
</example>
938
+

939
+
<informalexample>
940
+
<programlisting role="php">
941
+
<![CDATA[
942
+
<?php
658
943
// This will not work, and will result in a parse error, such as:
659
944
// Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
660
945
// This of course applies to using superglobals in strings as well
661
946
print "Hello $arr['fruit']";
662
947
print "Hello $_GET['foo']";
663
-

664
-
// Concatenation is another option
665
-
print "Hello " . $arr['fruit']; // Hello apple
666
948
?>
667
949
]]>
668
950
</programlisting>
...
...
@@ -762,11 +1044,11 @@ $error_descriptions[8] = "This is just an informal notice";
762
1044
<title>Converting to array</title>
763
1045

764
1046
<para>
765
-
For any of the types: <type>integer</type>, <type>float</type>,
766
-
<type>string</type>, <type>boolean</type> and <type>resource</type>,
1047
+
For any of the types <type>int</type>, <type>float</type>,
1048
+
<type>string</type>, <type>bool</type> and <type>resource</type>,
767
1049
converting a value to an <type>array</type> results in an array with a single
768
1050
element with index zero and the value of the scalar which was converted. In
769
-
other words, <literal>(array)$scalarValue</literal> is exactly the same as
1051
+
other words, <code>(array) $scalarValue</code> is exactly the same as
770
1052
<literal>array($scalarValue)</literal>.
771
1053
</para>
772
1054

...
...
@@ -777,11 +1059,50 @@ $error_descriptions[8] = "This is just an informal notice";
777
1059
exceptions: integer properties are unaccessible;
778
1060
private variables have the class name prepended to the variable
779
1061
name; protected variables have a '*' prepended to the variable name. These
780
-
prepended values have null bytes on either side. This can result in some
781
-
unexpected behaviour:
1062
+
prepended values have <literal>NUL</literal> bytes on either side.
1063
+
Uninitialized <link linkend="language.oop5.properties.typed-properties">typed properties</link>
1064
+
are silently discarded.
782
1065
</para>
783
1066

784
-
<informalexample>
1067
+
<example>
1068
+
<title>Converting to an Array</title>
1069
+
<programlisting role="php">
1070
+
<![CDATA[
1071
+
<?php
1072
+

1073
+
class A {
1074
+
private $B;
1075
+
protected $C;
1076
+
public $D;
1077
+
function __construct()
1078
+
{
1079
+
$this->{1} = null;
1080
+
}
1081
+
}
1082
+

1083
+
var_export((array) new A());
1084
+
?>
1085
+
]]>
1086
+
</programlisting>
1087
+
&example.outputs;
1088
+
<screen>
1089
+
<![CDATA[
1090
+
array (
1091
+
'' . "\0" . 'A' . "\0" . 'B' => NULL,
1092
+
'' . "\0" . '*' . "\0" . 'C' => NULL,
1093
+
'D' => NULL,
1094
+
1 => NULL,
1095
+
)
1096
+
]]>
1097
+
</screen>
1098
+
</example>
1099
+

1100
+
<para>
1101
+
These <literal>NUL</literal> can result in some unexpected behaviour:
1102
+
</para>
1103
+

1104
+
<example>
1105
+
<title>Casting an Object to an Array</title>
785
1106
<programlisting role="php">
786
1107
<![CDATA[
787
1108
<?php
...
...
@@ -799,7 +1120,20 @@ var_dump((array) new B());
799
1120
?>
800
1121
]]>
801
1122
</programlisting>
802
-
</informalexample>
1123
+
&example.outputs;
1124
+
<screen>
1125
+
<![CDATA[
1126
+
array(3) {
1127
+
["BA"]=>
1128
+
NULL
1129
+
["AA"]=>
1130
+
NULL
1131
+
["AA"]=>
1132
+
NULL
1133
+
}
1134
+
]]>
1135
+
</screen>
1136
+
</example>
803
1137

804
1138
<para>
805
1139
The above will appear to have two keys named 'AA', although one of them is
...
...
@@ -822,6 +1156,102 @@ var_dump((array) new B());
822
1156
</para>
823
1157
</sect2>
824
1158

1159
+
<sect2 xml:id="language.types.array.unpacking">
1160
+
<title>Array unpacking</title>
1161
+

1162
+
<para>
1163
+
An array prefixed by <code>...</code> will be expanded in place during array definition.
1164
+
Only arrays and objects which implement <interfacename>Traversable</interfacename> can be expanded.
1165
+
Array unpacking with <code>...</code> is available as of PHP 7.4.0.
1166
+
</para>
1167
+

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

1171
+
<example>
1172
+
<title>Simple array unpacking</title>
1173
+
<programlisting role="php">
1174
+
<![CDATA[
1175
+
<?php
1176
+
// Using short array syntax.
1177
+
// Also, works with array() syntax.
1178
+
$arr1 = [1, 2, 3];
1179
+
$arr2 = [...$arr1]; // [1, 2, 3]
1180
+
$arr3 = [0, ...$arr1]; // [0, 1, 2, 3]
1181
+
$arr4 = [...$arr1, ...$arr2, 111]; // [1, 2, 3, 1, 2, 3, 111]
1182
+
$arr5 = [...$arr1, ...$arr1]; // [1, 2, 3, 1, 2, 3]
1183
+

1184
+
function getArr() {
1185
+
return ['a', 'b'];
1186
+
}
1187
+
$arr6 = [...getArr(), 'c' => 'd']; // ['a', 'b', 'c' => 'd']
1188
+

1189
+
var_dump($arr1, $arr2, $arr3, $arr4, $arr5, $arr6);
1190
+
?>
1191
+
]]>
1192
+
</programlisting>
1193
+
</example>
1194
+
</para>
1195
+

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

1200
+
<example>
1201
+
<title>Array unpacking with duplicate key</title>
1202
+
<programlisting role="php">
1203
+
<![CDATA[
1204
+
<?php
1205
+
// string key
1206
+
$arr1 = ["a" => 1];
1207
+
$arr2 = ["a" => 2];
1208
+
$arr3 = ["a" => 0, ...$arr1, ...$arr2];
1209
+
var_dump($arr3); // ["a" => 2]
1210
+

1211
+
// integer key
1212
+
$arr4 = [1, 2, 3];
1213
+
$arr5 = [4, 5, 6];
1214
+
$arr6 = [...$arr4, ...$arr5];
1215
+
var_dump($arr6); // [1, 2, 3, 4, 5, 6]
1216
+
// Which is [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6]
1217
+
// where the original integer keys have not been retained.
1218
+
?>
1219
+
]]>
1220
+
</programlisting>
1221
+
</example>
1222
+
</para>
1223
+

1224
+
<note>
1225
+
<para>
1226
+
Keys that are neither integers nor strings throw a <classname>TypeError</classname>.
1227
+
Such keys can only be generated by a <interfacename>Traversable</interfacename> object.
1228
+
</para>
1229
+
</note>
1230
+
<note>
1231
+
<para>
1232
+
Prior to PHP 8.1, unpacking an array which has a string key is not supported:
1233
+
</para>
1234
+
<informalexample>
1235
+
<programlisting role="php">
1236
+
<![CDATA[
1237
+
<?php
1238
+

1239
+
$arr1 = [1, 2, 3];
1240
+
$arr2 = ['a' => 4];
1241
+
$arr3 = [...$arr1, ...$arr2];
1242
+
// Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5
1243
+

1244
+
$arr4 = [1, 2, 3];
1245
+
$arr5 = [4, 5];
1246
+
$arr6 = [...$arr4, ...$arr5]; // works. [1, 2, 3, 4, 5]
1247
+
?>
1248
+
]]>
1249
+
</programlisting>
1250
+
</informalexample>
1251
+
</note>
1252
+

1253
+
</sect2>
1254
+

825
1255
<sect2 xml:id="language.types.array.examples">
826
1256
<title>Examples</title>
827
1257

...
...
@@ -829,7 +1259,8 @@ var_dump((array) new B());
829
1259
The array type in PHP is very versatile. Here are some examples:
830
1260
</para>
831
1261

832
-
<informalexample>
1262
+
<example>
1263
+
<title>Array Versatility</title>
833
1264
<programlisting role="php">
834
1265
<![CDATA[
835
1266
<?php
...
...
@@ -843,6 +1274,8 @@ $a = array( 'color' => 'red',
843
1274

844
1275
$b = array('a', 'b', 'c');
845
1276

1277
+
var_dump($a, $b);
1278
+

846
1279
// . . .is completely equivalent with this:
847
1280
$a = array();
848
1281
$a['color'] = 'red';
...
...
@@ -860,10 +1293,12 @@ $b[] = 'c';
860
1293
// array('color' => 'red', 'taste' => 'sweet', 'shape' => 'round',
861
1294
// 'name' => 'apple', 0 => 4), and $b will be the array
862
1295
// array(0 => 'a', 1 => 'b', 2 => 'c'), or simply array('a', 'b', 'c').
1296
+

1297
+
var_dump($a, $b);
863
1298
?>
864
1299
]]>
865
1300
</programlisting>
866
-
</informalexample>
1301
+
</example>
867
1302

868
1303
<example>
869
1304
<title>Using array()</title>
...
...
@@ -876,15 +1311,17 @@ $map = array( 'version' => 4,
876
1311
'lang' => 'english',
877
1312
'short_tags' => true
878
1313
);
1314
+
var_dump($map);
879
1315

880
1316
// strictly numerical keys
1317
+
// this is the same as array(0 => 7, 1 => 8, ...)
881
1318
$array = array( 7,
882
1319
8,
883
1320
0,
884
1321
156,
885
1322
-10
886
1323
);
887
-
// this is the same as array(0 => 7, 1 => 8, ...)
1324
+
var_dump($array);
888
1325

889
1326
$switching = array( 10, // key = 0
890
1327
5 => 6,
...
...
@@ -895,9 +1332,11 @@ $switching = array( 10, // key = 0
895
1332
'02' => 77, // key = '02'
896
1333
0 => 12 // the value 10 will be overwritten by 12
897
1334
);
1335
+
var_dump($switching);
898
1336

899
1337
// empty array
900
1338
$empty = array();
1339
+
var_dump($empty);
901
1340
?>
902
1341
]]>
903
1342
<!-- TODO example of
...
...
@@ -934,8 +1373,8 @@ Do you like yellow?
934
1373
</example>
935
1374

936
1375
<para>
937
-
Changing the values of the <type>array</type> directly is possible since PHP
938
-
5 by passing them by reference. Before that, a workaround is necessary:
1376
+
Changing the values of the <type>array</type> directly is possible
1377
+
by passing them by reference.
939
1378
</para>
940
1379

941
1380
<example xml:id="language.types.array.examples.changeloop">
...
...
@@ -943,18 +1382,14 @@ Do you like yellow?
943
1382
<programlisting role="php">
944
1383
<![CDATA[
945
1384
<?php
946
-
// PHP 5
1385
+
$colors = array('red', 'blue', 'green', 'yellow');
1386
+

947
1387
foreach ($colors as &$color) {
948
-
$color = strtoupper($color);
1388
+
$color = mb_strtoupper($color);
949
1389
}
950
1390
unset($color); /* ensure that following writes to
951
1391
$color will not modify the last array element */
952
1392

953
-
// Workaround for older versions
954
-
foreach ($colors as $key => $color) {
955
-
$colors[$key] = strtoupper($color);
956
-
}
957
-

958
1393
print_r($colors);
959
1394
?>
960
1395
]]>
...
...
@@ -982,7 +1417,7 @@ Array
982
1417
<programlisting role="php">
983
1418
<![CDATA[
984
1419
<?php
985
-
$firstquarter = array(1 => 'January', 'February', 'March');
1420
+
$firstquarter = array(1 => 'January', 'February', 'March');
986
1421
print_r($firstquarter);
987
1422
?>
988
1423
]]>
...
...
@@ -992,9 +1427,9 @@ print_r($firstquarter);
992
1427
<![CDATA[
993
1428
Array
994
1429
(
995
-
[1] => 'January'
996
-
[2] => 'February'
997
-
[3] => 'March'
1430
+
[1] => January
1431
+
[2] => February
1432
+
[3] => March
998
1433
)
999
1434
]]>
1000
1435
</screen>
...
...
@@ -1011,6 +1446,8 @@ while (false !== ($file = readdir($handle))) {
1011
1446
$files[] = $file;
1012
1447
}
1013
1448
closedir($handle);
1449
+

1450
+
var_dump($files);
1014
1451
?>
1015
1452
]]>
1016
1453
</programlisting>
...
...
@@ -1025,7 +1462,7 @@ closedir($handle);
1025
1462

1026
1463
<example>
1027
1464
<title>Sorting an array</title>
1028
-
<programlisting role="php">
1465
+
<programlisting role="php" annotations="non-interactive">
1029
1466
<![CDATA[
1030
1467
<?php
1031
1468
sort($files);
...
...
@@ -1062,6 +1499,7 @@ $fruits = array ( "fruits" => array ( "a" => "orange",
1062
1499
"third"
1063
1500
)
1064
1501
);
1502
+
var_dump($fruits);
1065
1503

1066
1504
// Some examples to address values in the array above
1067
1505
echo $fruits["holes"][5]; // prints "second"
...
...
@@ -1070,6 +1508,7 @@ unset($fruits["holes"][0]); // remove "first"
1070
1508

1071
1509
// Create a new multi-dimensional array
1072
1510
$juices["apple"]["green"] = "good";
1511
+
var_dump($juices);
1073
1512
?>
1074
1513
]]>
1075
1514
</programlisting>
...
...
@@ -1081,7 +1520,8 @@ $juices["apple"]["green"] = "good";
1081
1520
<type>array</type> by reference.
1082
1521
</para>
1083
1522

1084
-
<informalexample>
1523
+
<example>
1524
+
<title>Array Copying</title>
1085
1525
<programlisting role="php">
1086
1526
<![CDATA[
1087
1527
<?php
...
...
@@ -1092,10 +1532,12 @@ $arr2[] = 4; // $arr2 is changed,
1092
1532

1093
1533
$arr3 = &$arr1;
1094
1534
$arr3[] = 4; // now $arr1 and $arr3 are the same
1535
+

1536
+
var_dump($arr1, $arr2, $arr3);
1095
1537
?>
1096
1538
]]>
1097
1539
</programlisting>
1098
-
</informalexample>
1540
+
</example>
1099
1541

1100
1542
</sect2>
1101
1543
</sect1>
1102
1544



Translation status