php - 我应该如何 PHPDoc 回调？

Question

我有一个方法可以从数据库中提取经过修改的预序树横向树，并使用回调函数对其进行过滤。例如:

/**
 * 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;
}

我不确定变量 $filter 的 PHPDoc 应该是什么 -- 它是一个回调，这是我已经指出的，但我不确定这是否正确。

此外，任何其他关于此代码质量(或缺乏质量)的评论将不胜感激:)

Answer 1

正确的类型提示是callable，它已经在 PhpStorm 中使用了很长时间，并且是 PSR-5 的一部分。目前正在规范中。

(我很惊讶没有其他人提到 callable，这不是什么新鲜事，多年来一直在各处使用 - 据我所知，callback 不是也从来没有被定义PHP pseudo-type )

请注意，callable 不仅包括闭包，还包括“老派”PHP 回调，例如array($object, 'methodName') 或 array('ClassName', 'methodName') 甚至 'function_name' - 最大化你的 API 的有用性，你应该涵盖所有这些用例，这很容易，因为 call_user_func和 call_user_func_array支持所有四种可调用对象:函数名作为字符串、对象/方法名、类/方法名和闭包。