php / php/doc-en

Callables: clarify behavior on instance callables

Open
#4,355 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
XML
Stars
596
Forks
890
Avg merge
1d 15h
Merged PRs (30d)
55

Description

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the callable manual page at https://www.php.net/manual/en/language.types.callable.php and review the existing visibility wording and examples. Update the documentation to explicitly explain that protected and private methods passed as callables are not callable from outside their declaring class, including the instance-callable case; the page should make this behavior unambiguous.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.