[DOC-CVS] [doc-en] master: Fix type juggling notes for list() and array destructuring (#3680)

Author: Tisza Gergő (tgr)
Committer: GitHub (web-flow)
Pusher: DanielEScherzer
Date: 2025-08-23T22:30:09-07:00

Commit: https://github.com/php/doc-en/commit/eaec4ab10a65c4515ee2fb899d06e89bae3754b0
Raw diff: https://github.com/php/doc-en/commit/eaec4ab10a65c4515ee2fb899d06e89bae3754b0.diff

Fix type juggling notes for list() and array destructuring (#3680)

Update notes about the handling of missing keys and non-arrays
during array destructuring to match the behavior seen on
3v4l.org, which doesn't issue a warning or notice in some cases
where the documentation claims it does. Also update list() docs
to provide the same information.

list():
* missing key: https://3v4l.org/bYBt6
* destructuring an integer: https://3v4l.org/7lNhK
* a boolean: https://3v4l.org/p5LDd
* a string: https://3v4l.org/KHSAH
* null: https://3v4l.org/lk1iu

array notation:
* missing key: https://3v4l.org/KCiTC
* destructuring an integer: https://3v4l.org/louVG
* a boolean: https://3v4l.org/SWL5L
* a string: https://3v4l.org/aK90L
* null: https://3v4l.org/Y8cOY

Fixes #3640.

Changed paths:
  M  language/types/array.xml
  M  reference/array/functions/list.xml


Diff:

diff --git a/language/types/array.xml b/language/types/array.xml
index 98a18a2766d5..8338dd20fd09 100644
--- a/language/types/array.xml
+++ b/language/types/array.xml
@@ -734,6 +734,11 @@ echo $b, PHP_EOL;    // prints 1
       issued, and the result will be &null;.
     </para>
    </note>
+   <note>
+    <para>
+      Destructuring a scalar value assigns &null; to all variables.
+    </para>
+   </note>
   </sect3>
 
  </sect2><!-- end syntax -->
diff --git a/reference/array/functions/list.xml b/reference/array/functions/list.xml
index 38265af3af9d..4c22c70084fd 100644
--- a/reference/array/functions/list.xml
+++ b/reference/array/functions/list.xml
@@ -16,8 +16,8 @@
    Like <function>array</function>, this is not really a function,
    but a language construct. <function>list</function> is used to
    assign a list of variables in one operation.
-   Strings can not be unpacked and <function>list</function> expressions 
-   can not be completely empty.
+   Only arrays and objects that implement <link linkend="class.arrayaccess">ArrayAccess</link> can be unpacked.
+   <function>list</function> expressions can not be completely empty.
   </para>
   <note>
    <para>
@@ -30,6 +30,19 @@
    destructuring of arrays with non-integer or non-sequential keys. For more details on
    array destructuring, see the <link linkend="language.types.array.syntax.destructuring">array destructuring section</link>.
   </para>
+  <note>
+   <para>
+    Attempting to access an array key which has not been defined is
+    the same as accessing any other undefined variable:
+    an <constant>E_WARNING</constant>-level error message
+    (<constant>E_NOTICE</constant>-level prior to PHP 8.0.0) will be
+    issued, and the result will be &null;.
+   </para>
+   <para>
+    Attempting to unpack a scalar assigns &null; to all variables.
+    Attempting to unpack an object that does not implement ArrayAccess is a fatal error.
+   </para>
+  </note>
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;