Как мне PHPDoc обратного вызова? - PullRequest
Новая
       10

Как мне PHPDoc обратного вызова?

27 голосов
/ 07 февраля 2011

У меня есть метод, который извлекает измененное дерево трансверсального дерева предзаказа из базы данных и фильтрует его с помощью функции обратного вызова. Например: 

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

Я не уверен, каким должен быть PHPDoc для переменной $filter - это обратный вызов, что я и указал, но я не уверен, правильно ли это.

Кроме того, любые другие комментарии о качестве (или его отсутствии) в этом коде будут приветствоваться:)

Ответы [ 4 ]

35 голосов
/ 11 февраля 2014

Правильный тип подсказки - callable, который долгое время был доступен, например, в PhpStorm, и является частью PSR-5 , которая в настоящее время соответствует спецификации.

(Я удивлен, что никто больше не упомянул callable, в этом нет ничего нового, и он использовался повсеместно в течение многих лет - насколько мне известно, callback не является и никогда не был определенным PHP псевдотипа ) * +1010 *

Обратите внимание, что callable включает не только замыкания, но и обратные вызовы PHP "старой школы", например, array($object, 'methodName') или array('ClassName', 'methodName') и даже 'function_name' - чтобы максимизировать полезность вашего API, вы должны охватить все эти варианты использования, что довольно просто, так как оба call_user_func и call_user_func_array поддерживает все четыре разновидности вызываемых объектов: имя функции в виде строки, имя объекта / метода, имя класса / метода и замыкание.

6 голосов
/ 07 февраля 2011

«обратный вызов» работает как действительный тип данных в phpDocumentor ... Я только что проверил это ... используя PHP 5.2.4, по крайней мере.Возможно, что «допустимые типы данных» зависят от версии PHP, с которой вы запускаете phpDocumentor.

1 голос
/ 07 февраля 2011

phpDoc на самом деле не указывает, какие типы переменных принимаются, просто они должны быть именами допустимых типов переменных php. В этом случае «обратный вызов» будет правильным. Это имя псевдотипа в PHP.

0 голосов
/ 07 февраля 2011

Документация для тега @param, кажется, не обновлялась в течение эонов, поэтому в ней ничего не говорится о замыканиях или даже обратных вызовах, сделанных с помощью create_function().

Если phpDocumentor отказываетсяПризнав callback типом данных, вам придется использовать mixed.

...