[DOC-CVS] [doc-en] master: Clarify forward_static_call docs (#5784)

Author: USAMI Kenta (zonuexe)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-21T20:09:49+02:00

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

Clarify forward_static_call docs (#5784)

* Clarify forward_static_call docs

* Update reference/funchand/functions/forward-static-call-array.xml

Co-authored-by: Louis-Arnaud <[email protected]>

* Update reference/funchand/functions/forward-static-call-array.xml

Co-authored-by: Louis-Arnaud <[email protected]>

* Update reference/funchand/functions/forward-static-call.xml

Co-authored-by: Louis-Arnaud <[email protected]>

* Apply suggestion from @lacatoire

---------

Co-authored-by: Louis-Arnaud <[email protected]>

Changed paths:
  M  reference/funchand/functions/forward-static-call-array.xml
  M  reference/funchand/functions/forward-static-call.xml


Diff:

diff --git a/reference/funchand/functions/forward-static-call-array.xml b/reference/funchand/functions/forward-static-call-array.xml
index fcb899adbb32..cc763af464cc 100644
--- a/reference/funchand/functions/forward-static-call-array.xml
+++ b/reference/funchand/functions/forward-static-call-array.xml
@@ -3,7 +3,8 @@
 <refentry xml:id="function.forward-static-call-array" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>forward_static_call_array</refname>
-  <refpurpose>Call a static method and pass the arguments as array</refpurpose>
+  <refpurpose>Call a callback with an array of parameters, preserving the
+  current called class</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -17,10 +18,12 @@
    Calls a user defined function or method given by the <parameter>callback</parameter>
    parameter, with arguments passed as an array, similarly to
    <function>call_user_func_array</function>.
-   When called from within a method context, it uses the
-   <link linkend="language.oop5.late-static-bindings">late static binding</link>.
-   When called outside a class context, it behaves like
-   <function>call_user_func_array</function>, without late static binding.
+   When called from within a method context and calling a method callback,
+   it makes a
+   <link linkend="language.oop5.late-static-bindings">forwarding call</link>,
+   so <literal>static::</literal> inside the method resolves to the same called
+   class as in the caller. This is useful for static method callbacks that
+   should behave like <literal>self::</literal> or <literal>parent::</literal>.
   </simpara>
   <note>
    <simpara>
@@ -49,14 +52,14 @@
     <varlistentry>
      <term><parameter>args</parameter></term>
      <listitem>
-      <para>
-       One parameter, gathering all the method parameter in one array.
-      </para>
+      <simpara>
+       The parameters to be passed to the callback, as an array.
+      </simpara>
       <note>
-       <para>
-        Note that the parameters for <function>forward_static_call_array</function> are
-        not passed by reference.
-       </para>
+       <simpara>
+        To pass a parameter by reference, the corresponding element in
+        <parameter>args</parameter> must be a reference.
+       </simpara>
       </note>
      </listitem>
     </varlistentry>
diff --git a/reference/funchand/functions/forward-static-call.xml b/reference/funchand/functions/forward-static-call.xml
index 4a89c8568124..45e52db712c8 100644
--- a/reference/funchand/functions/forward-static-call.xml
+++ b/reference/funchand/functions/forward-static-call.xml
@@ -3,7 +3,7 @@
 <refentry xml:id="function.forward-static-call" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>forward_static_call</refname>
-  <refpurpose>Call a static method</refpurpose>
+  <refpurpose>Call a callback while preserving the current called class</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -13,13 +13,16 @@
    <methodparam><type>callable</type><parameter>callback</parameter></methodparam>
    <methodparam rep="repeat"><type>mixed</type><parameter>args</parameter></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    Calls a user defined function or method given by the <parameter>callback</parameter>
    parameter, with the following arguments. This function must be called within a method
    context, it can't be used outside a class.
-   It uses the <link linkend="language.oop5.late-static-bindings">late static
-   binding</link>.
-  </para>
+   When calling a method callback, it makes a
+   <link linkend="language.oop5.late-static-bindings">forwarding call</link>,
+   so <literal>static::</literal> inside the method resolves to the same called
+   class as in the caller. This is useful for static method callbacks that
+   should behave like <literal>self::</literal> or <literal>parent::</literal>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -39,9 +42,9 @@
     <varlistentry>
      <term><parameter>args</parameter></term>
      <listitem>
-      <para>
-       Zero or more parameters to be passed to the function.
-      </para>
+      <simpara>
+       Zero or more parameters to be passed to the callback.
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>