[PHP 8.1] Document Array Unpacking with [int|string] Keys. (#1171)

Co-authored-by: George Peter Banyard <girgias@php.net>

appendices/migration81/new-features.xml

@@ -31,8 +31,17 @@
    <title>Array Unpacking with String Keys</title>
 
    <para>
-    Added support for array unpacking with strings keys.
-    <!-- TODO Add an example -->
+    Added support for <link linkend="language.types.array.unpacking">array unpacking with strings keys</link>.
+    <informalexample>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$arr1 = [1, 'a'];
+$arr2 = [...$arr1, 'c' => 'd']; //[1, 'a', 'c' => 'd']
+?>
+]]>
+     </programlisting>
+    </informalexample>
    </para>
    <!-- RFC: https://wiki.php.net/rfc/array_unpacking_string_keys -->
   </sect3>

language/types/array.xml

@@ -940,6 +940,100 @@ array(3) {
   </para>
  </sect2>
 
+ <sect2 xml:id="language.types.array.unpacking">
+  <title>Array unpacking</title>
+
+  <para>
+   An array prefixed by <code>...</code> will be expanded in place during the definition of the array.
+   Only arrays and objects which implement <interfacename>Traversable</interfacename> can be expanded.
+   Array unpacking with <code>...</code> is available as of PHP 7.4.0.
+  </para>
+
+  <para>
+   It's possible to expand multiple times, and add normal elements before or after the <code>...</code> operator:
+
+   <example>
+    <title>Simple array unpacking</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Using short array syntax.
+// Also, works with array() syntax.
+$arr1 = [1, 2, 3];
+$arr2 = [...$arr1]; //[1, 2, 3]
+$arr3 = [0, ...$arr1]; //[0, 1, 2, 3]
+$arr4 = [...$arr1, ...$arr2, 111]; //[1, 2, 3, 1, 2, 3, 111]
+$arr5 = [...$arr1, ...$arr1]; //[1, 2, 3, 1, 2, 3]
+
+function getArr() {
+  return ['a', 'b'];
+}
+$arr6 = [...getArr(), 'c' => 'd']; //['a', 'b', 'c' => 'd']
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+
+  <para>
+   Unpacking an array with the <code>...</code> operator follows the semantics of the <function>array_merge</function> function.
+   That is, later string keys overwrite earlier ones and integer keys are renumbered:
+
+   <example>
+    <title>Array unpacking with duplicate key</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// string key
+$arr1 = ["a" => 1];
+$arr2 = ["a" => 2];
+$arr3 = ["a" => 0, ...$arr1, ...$arr2];
+var_dump($arr3); // ["a" => 2]
+
+// integer key
+$arr4 = [1, 2, 3];
+$arr5 = [4, 5, 6];
+$arr6 = [...$arr4, ...$arr5];
+var_dump($arr6); // [1, 2, 3, 4, 5, 6]
+// Which is [0 => 1, 1 => 2, 2 => 3, 3 => 4, 4 => 5, 5 => 6]
+// where the original integer keys have not been retained.
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+
+  <note>
+   <para>
+    Keys that are neither integers nor strings throw a <classname>TypeError</classname>.
+    Such keys can only be generated by a <interfacename>Traversable</interfacename> object.
+   </para>
+  </note>
+  <note>
+   <para>
+    Prior to PHP 8.1, unpacking an array which has a string key is not supported:
+   </para>
+   <informalexample>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$arr1 = [1, 2, 3];
+$arr2 = ['a' => 4];
+$arr3 = [...$arr1, ...$arr2];
+// Fatal error: Uncaught Error: Cannot unpack array with string keys in example.php:5
+
+$arr4 = [1, 2, 3];
+$arr5 = [4, 5];
+$arr6 = [...$arr4, ...$arr5]; // works. [1, 2, 3, 4, 5]
+?>
+]]>
+    </programlisting>
+   </informalexample>
+  </note>
+
+ </sect2>
+
  <sect2 xml:id="language.types.array.examples">
   <title>Examples</title>