From 69c71b12af8f5b314f741bd5c38c001c89627d9c Mon Sep 17 00:00:00 2001
From: Vincent Wong <vincentwwy168@gmail.com>
Date: Sat, 28 Jun 2025 22:28:23 +0800
Subject: [PATCH 1/3] Warn about passing protected/private callables

---
 language/types/callable.xml | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/language/types/callable.xml b/language/types/callable.xml
index 42665a778d62..7a76571c0785 100644
--- a/language/types/callable.xml
+++ b/language/types/callable.xml
@@ -30,10 +30,18 @@
   <para>
    A method of an instantiated <type>object</type> is passed as an
    <type>array</type> containing an <type>object</type> at index 0 and the
-   method name at index 1. Accessing protected and private methods from
-   within a class is allowed.
+   method name at index 1. Passing protected and private methods
+   with the <type>callable</type> syntax is allowed.
   </para>
 
+  <note>
+   <para>
+    If a callable of a protected or a private method is invoked from outside the class
+    with no visibility of said methods (e.g. being called from a POSIX signal handler),
+    a runtime error is thrown because the callable is invalid at the time of invocation.
+   </para>
+  </note>
+
   <para>
    Static class methods can also be passed without instantiating an
    <type>object</type> of that class by either, passing the class name

From 9640ab72ee0d45eaf037fcb7c722d723c041ce99 Mon Sep 17 00:00:00 2001
From: Vincent Wong <vincentwwy168@gmail.com>
Date: Sat, 28 Jun 2025 23:00:29 +0800
Subject: [PATCH 2/3] Provide more callback examples

---
 language/types/callable.xml | 54 +++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/language/types/callable.xml b/language/types/callable.xml
index 7a76571c0785..d369b54d3fab 100644
--- a/language/types/callable.xml
+++ b/language/types/callable.xml
@@ -164,6 +164,60 @@ print implode(' ', $new_numbers);
    </example>
   </para>
 
+  <para>
+   <example>
+    <title>
+     Manually invoking callbacks
+    </title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+// define a callback handler that executes the callable (no parameters)
+function invokeCallback(callable $theCallback) {
+    $theCallback();
+}
+
+// prints "42"
+invokeCallback(function () {
+    echo "42" . PHP_EOL;
+});
+
+// define a callback handler that executes the callable with a parameter
+function processNumber(callable $processor, int $theNumber) {
+    // process a number, and print its result
+    $result = $processor($theNumber);
+    echo $result . PHP_EOL;
+}
+
+// prints "72"
+processNumber(fn ($x) => $x * 3, 24);
+
+// define a class implementing the __invoke method
+class NumberTripler
+{
+    public function __invoke($x)
+    {
+        return $x * 3;
+    }
+}
+
+// prints "15"
+$tripler = new NumberTripler();
+processNumber($tripler, 5);
+?>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+42
+72
+15
+]]>
+    </screen>
+   </example>
+  </para>
+
   &note.func-callback-exceptions;
  </sect2>
 

From 4d9d72cce1368f1ccfb374264e05345344ff995f Mon Sep 17 00:00:00 2001
From: Vincent Wong <vincentwwy168@gmail.com>
Date: Sat, 28 Jun 2025 23:18:38 +0800
Subject: [PATCH 3/3] Add the "private method" example

---
 language/types/callable.xml | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/language/types/callable.xml b/language/types/callable.xml
index d369b54d3fab..fa6065ec292a 100644
--- a/language/types/callable.xml
+++ b/language/types/callable.xml
@@ -205,6 +205,25 @@ class NumberTripler
 // prints "15"
 $tripler = new NumberTripler();
 processNumber($tripler, 5);
+
+// define a class with a private instance method, to be called with the callable syntax
+class HiddenFactory
+{
+    private function hiddenWork()
+    {
+        echo "256" . PHP_EOL;
+    }
+
+    public function getProof()
+    {
+        return Closure::fromCallable([$this, 'hiddenWork']);
+    }
+}
+
+// prints "256"
+$factory = new HiddenFactory();
+$theProof = $factory->getProof();
+invokeCallback($theProof);
 ?>
     </programlisting>
     &example.outputs;
@@ -213,6 +232,7 @@ processNumber($tripler, 5);
 42
 72
 15
+256
 ]]>
     </screen>
    </example>