[DOC-CVS] [doc-en] master: Document named arguments support in Reflection ...Args methods (#5225)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-28T13:48:12+02:00

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

Document named arguments support in Reflection ...Args methods (#5225)

Document that args keys are interpreted as parameter names since PHP 8.0
for ReflectionClass::newInstanceArgs, and describe the current contract of
the args parameter on that method and on ReflectionMethod::invokeArgs and
ReflectionFunction::invokeArgs: numeric keys are positional, string keys
are named arguments, and an Error is thrown for a numeric key after a
string key or for a string key matching no parameter.

Fixes: #3355

Changed paths:
  M  reference/reflection/reflectionclass/newinstanceargs.xml
  M  reference/reflection/reflectionfunction/invokeargs.xml
  M  reference/reflection/reflectionmethod/invokeargs.xml


Diff:

diff --git a/reference/reflection/reflectionclass/newinstanceargs.xml b/reference/reflection/reflectionclass/newinstanceargs.xml
index c98387390c11..363889c371f6 100644
--- a/reference/reflection/reflectionclass/newinstanceargs.xml
+++ b/reference/reflection/reflectionclass/newinstanceargs.xml
@@ -26,9 +26,24 @@
     <varlistentry>
      <term><parameter>args</parameter></term>
      <listitem>
-      <para>
+      <simpara>
        The parameters to be passed to the class constructor as an <type>array</type>.
-      </para>
+      </simpara>
+      <simpara>
+       If the keys of <parameter>args</parameter> are all numeric, the keys are
+       ignored and each element is passed to the constructor as a positional
+       argument, in order.
+      </simpara>
+      <simpara>
+       If any keys of <parameter>args</parameter> are strings, those elements are
+       passed to the constructor as named arguments, with the name given by the
+       key.
+      </simpara>
+      <simpara>
+       An <exceptionname>Error</exceptionname> is thrown if a numeric key in
+       <parameter>args</parameter> appears after a string key, or if a string key
+       does not match the name of any constructor parameter.
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -52,7 +67,29 @@
    and the <parameter>args</parameter> parameter contains one or more parameters.
   </para>
  </refsect1>
- 
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>8.0.0</entry>
+      <entry>
+       <parameter>args</parameter> keys will now be interpreted as parameter names, instead of being silently ignored.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
diff --git a/reference/reflection/reflectionfunction/invokeargs.xml b/reference/reflection/reflectionfunction/invokeargs.xml
index bd05ede50738..7f3399e78417 100644
--- a/reference/reflection/reflectionfunction/invokeargs.xml
+++ b/reference/reflection/reflectionfunction/invokeargs.xml
@@ -25,10 +25,25 @@
     <varlistentry>
      <term><parameter>args</parameter></term>
      <listitem>
-      <para>
-       The passed arguments to the function as an array, much like 
-       <function>call_user_func_array</function> works.
-      </para>
+      <simpara>
+       The parameters to be passed to the function, as an <type>array</type>,
+       much like <function>call_user_func_array</function> works.
+      </simpara>
+      <simpara>
+       If the keys of <parameter>args</parameter> are all numeric, the keys are
+       ignored and each element is passed to the function as a positional
+       argument, in order.
+      </simpara>
+      <simpara>
+       If any keys of <parameter>args</parameter> are strings, those elements are
+       passed to the function as named arguments, with the name given by the
+       key.
+      </simpara>
+      <simpara>
+       An <exceptionname>Error</exceptionname> is thrown if a numeric key in
+       <parameter>args</parameter> appears after a string key, or if a string key
+       does not match the name of any parameter of the function.
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>
diff --git a/reference/reflection/reflectionmethod/invokeargs.xml b/reference/reflection/reflectionmethod/invokeargs.xml
index afe7af6f7671..1c241534c0f3 100644
--- a/reference/reflection/reflectionmethod/invokeargs.xml
+++ b/reference/reflection/reflectionmethod/invokeargs.xml
@@ -35,9 +35,24 @@
     <varlistentry>
      <term><parameter>args</parameter></term>
      <listitem>
-      <para>
-       The parameters to be passed to the function, as an <type>array</type>.
-      </para>
+      <simpara>
+       The parameters to be passed to the method, as an <type>array</type>.
+      </simpara>
+      <simpara>
+       If the keys of <parameter>args</parameter> are all numeric, the keys are
+       ignored and each element is passed to the method as a positional
+       argument, in order.
+      </simpara>
+      <simpara>
+       If any keys of <parameter>args</parameter> are strings, those elements are
+       passed to the method as named arguments, with the name given by the
+       key.
+      </simpara>
+      <simpara>
+       An <exceptionname>Error</exceptionname> is thrown if a numeric key in
+       <parameter>args</parameter> appears after a string key, or if a string key
+       does not match the name of any parameter of the method.
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>