Callables: clarify behavior on instance callables

[Vectorial1024]

From manual page: https://www.php.net/manual/en/language.types.callable.php

---

While debugging why a piece of code involving object instance callables acts as if it was never called, I have discovered a behavior that is only implied by the docs. It is best if this behavior is directly pointed out.

Consider:

class SignalListener {
    public function __construct() {
        pcntl_signal(SIGTERM, [$this, 'signalHandler']);
    }

    private function signalHandler() {
        echo 'signal!';
    }
}

Then:

$listener = new SignalListener();
posix_kill(getmypid(), SIGTERM);

One may expect that $listener->signalHandler() is called since the callable might actually be referenced directly by the runtime somehow, so perhaps the PCNTL function in question might actually be able to call $listener->signalHandler(). This misconception therefore prompts the following expected output:

signal!

...but actually, this triggers the following error:

Invalid callback SignalListener::signalHandler, cannot access private method SignalListener::signalHandler [...]

---

Currently, the docs mention that "accessing protected and private methods from within a class is allowed", but it does not mention what happens when protected/private methods are being passed as callables to outside a class, such as the PCNTL module functions that exists freely with no namespaces or classes.

It is best if the docs can explicitly mention that protected/private members inside a class are still not callable outside its own class even via the callables syntax.

It does not seem like this behavior will change, and this can be a gotcha moment for inexperienced devs, so this is worthy of being put into the official docs.

[damianwadley]

The answer is fairly straightforward: callable means the thing receiving the array (or whatever) is able to call it. In other words, this

function execute_the_callable(callable $thing) {
    $thing(/* whatever args are necessary */);
}

should always be able to work. If the thing receiving the "callable" isn't able to invoke the value then the value isn't valid as a callable.

So while [$this, "signalHandler"] is certainly callable from within the SignalListener class, it's referencing a private method so it won't be callable from outside that class. Including from pcntl_signal [1]. So that means it won't be valid for pcntl_signal's callable second argument.
For the record, you can avoid having to make the handler public by (a) using an inline function instead of a discrete method on the class, as in pcntl_signal(SIGTERM, function() { ... }) [2], or (b) using Closure::fromCallable [3] to create a Closure object which you can then pass as the handler argument.

Because "callable" isn't a first-class concept. PHP isn't converting that array into some sort of special type of value. That array there really is just an array that happens to fit the syntax of a callable thing, like how "123" is really just a string that happens to be made up of digit characters, and 0xDEADBEEF is really just a number that happens to be written with letters.

Anyway, do you have some specific suggestions on how the docs could be improved such that they would be able to explain the missing information you needed to know? I'm asking because it's hard for someone who does understand a thing to write good documentation for readers who don't understand the thing.
If you're feeling especially motivated, you can even submit a pull request which edits callable.xml - yes, it's XML, but it's really not that scary if you look at it.

---

[1] Well, not pcntl_signal per se, rather it won't be callable from whatever internal mechanism is responding to the SIGTERM and invoking the handler.
[2] A function that does function() { $this->signalHandler(); } would also do the job: the function itself isn't limited by being private, and it's defined inside the class so it would be allowed to call the signalHandler method.
[3] If your next thought is "but fromCallable also takes a callable so how would that work any differently?" then (1) that's good thinking, and (2) the answer is "because fromCallable does special PHP internals magic to allow it to be used that way".

[Vectorial1024]

I am not sure, but right now I am learning a few things, both from my discovery of "no-private callables", and the comment info of "closures are valid for callable vartype". Gotta need some time to digest these, and then maybe open a PR to improve the docs. The docs being written in XML should not be an issue to me (I think).

But I am thinking the theme would be sth like "callables is not a first class vartype, just like how iterable is also not a first class vartype but only a magic sugar for (later PHP versions) ArrayAccess&Traversable", or something along the lines of "functions inside callables must still obey the usual visibility rules", etc etc.

Digest/think for now.

[Girgias]

There is a third option from recent PHP version which is return $this->privateMethod(...) which will return a Closure that you can call from wherever.

In general, you want Closure as those do not have the weird scoping issues that callable has.

[Vectorial1024]

While I haven't started organizing the new docs yet, it really seems like we should also improve the documentation of the Closure class, since callable and Closure are so similar yet fundamentally different.

[Girgias]

Yes, but the whole https://www.php.net/manual/en/language.functions.php sections requires a rewrite IMHO.
Where closures are somewhat describes as well.