How should I PHPDoc a callback?

Question

I have a method which extracts a modified preorder tree transversal tree from the database, and filters that using a callback function. For example:

/**
 * Recursive function for building the Cas_Template_TreeNode.
 *
 * @static
 * @param array $rows
 * @param callback $filter A function to filter the tree by (return a value convertible to false to remove the item from the tree)
 * @return array
 */
private static function MakeTreeGivenDbRows($rows, $filter = null)
{
    if ($filter === null)
    {
        $filter = function($unused)
        {
            return true;
        };
    }
    $result = array();
    $childrenCount = 0;
    for ($idx = 0; $idx < count($rows); $idx += $childrenCount + 1)
    {
        $current = $rows[$idx];
        $childrenCount = self::ChildrenCountFromRow($current);
        if (!$filter($current))
        {
            continue;
        }
        $childrenStartAt = $idx + 1;
        $childRows = array_slice($rows, $childrenStartAt, $childrenCount);
        $children = self::MakeTreeGivenDbRows($childRows, $filter);
        $result[] = new Cas_Template_TreeNode(self::MakeNodeGivenDbRow($current), $children);
    }
    if (empty($result))
    {
        return null;
    }
    return $result;
}

I'm not sure what the PHPDoc should be for the variable $filter -- it's a callback, which is what I've indicated, but I'm not sure if that's correct.

Also, any other comments on the quality (or lack thereof) in this code would be appreciated :)

score 36 · Accepted Answer · edited Sep 02 '16 at 19:01

The correct type-hint is callable, which has been available in e.g PhpStorm for a long time, and is part of PSR-5 which is currently under specification.

(I'm surprised nobody else mentioned callable, it's nothing new and has been used everywhere for years - to my knowledge, callback is not and never was a defined PHP pseudo-type)

Note that callable includes not just closures, but also "old school" PHP callbacks, e.g. array($object, 'methodName') or array('ClassName', 'methodName') and even 'function_name'- to maximize the usefulness of your API, you should cover all of those use-cases, which is quite easy, since both call_user_func and call_user_func_array support all four varieties of callables: function-name as string, object/method-name, class/method-name and closure.

When all these answers were written, `callback` was the correct answer. To quote the PHP pseudo-types article to which you linked: "callback pseudo-types was used in this documentation before callable type hint was introduced by PHP 5.4. It means exactly the same." All the other answers and question predate PHP 5.4, so they were right at the time. — Billy ONeal, Feb 12 '14 at 01:18

score 6 · Answer 2 · answered Feb 07 '11 at 19:19

6

"callback" does work as a valid datatype in phpDocumentor... I just verified it... using PHP 5.2.4, at least. It's feasible that "valid datatypes" depend on the PHP version you run phpDocumentor with.

answered Feb 07 '11 at 19:19

ashnazg

6,558
2
32
39

2

This answer was correct at the time it was written. However, it is no longer the correct answer as of PHP 5.4. – Billy ONeal Feb 12 '14 at 01:20

score 1 · Answer 3 · answered Feb 07 '11 at 07:46

1

phpDoc doesn't really specify what the accepted variable types are, just that they should be the names of valid php variable types. In this case "callback" would be correct. That is the name of the pseudo-type in PHP.

answered Feb 07 '11 at 07:46

Lèse majesté

7,923
2
33
44

score 0 · Answer 4 · answered Feb 07 '11 at 07:33

0

The documentation for the @param tag doesn't seem to have been updated in eons, so it doesn't say anything about closures or even callbacks made with create_function().

If phpDocumentor refuses to recognize callback as a data type, you'll have to go with mixed.

answered Feb 07 '11 at 07:33

BoltClock

700,868
160
1,392
1,356

I'm not sure if it recognises `callback` as a datatype or not. – Billy ONeal Feb 07 '11 at 07:33
@Billy ONeal: I guess you'd have to run the PHP files through phpDocumentor and find out. Or if you're just doing this informally without needing to generate the doc pages, just calling it `callback` wouldn't hurt. – BoltClock Feb 07 '11 at 07:36

How should I PHPDoc a callback?

4 Answers4