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 伪类型）

请注意可调用不仅包括闭包，还包括“老派”PHP 回调，例如 array($object, 'methodName') 或 array('ClassName', 'methodName') 以及甚至 'function_name' - 为了最大限度地发挥 API 的实用性，您应该涵盖所有这些用例，这很容易，因为 call_user_func 和 call_user_func_array 支持所有四种类型可调用对象：字符串形式的函数名称、对象/方法名称、类/方法名称和闭包。

Answer 2

“回调”确实可以作为 phpDocumentor 中的有效数据类型...我刚刚验证了它...至少使用 PHP 5.2.4。 “有效数据类型”可能取决于您运行 phpDocumentor 的 PHP 版本。

Answer 3

phpDoc 并没有真正指定接受的变量类型是什么，只是它们应该是有效的 php 变量类型的名称。在这种情况下，“回调”是正确的。这是 PHP 中伪类型的名称。

Answer 4

@param 标记的文档似乎已经很久没有更新了，因此它没有说明任何有关闭包甚至使用 create_function() 进行的回调的内容。

如果 phpDocumentor 拒绝将callback识别为数据类型，则必须使用mixed。