¿Cómo debo PHPDoc una devolución de llamada?


Tengo un método que extrae un árbol transversal de preorden modificado de la base de datos, y lo filtra usando una función de devolución de llamada. Por ejemplo:

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

No estoy seguro de cuál debería ser el PHPDoc para la variable $filter 's es una devolución de llamada, que es lo que he indicado, pero no estoy seguro de si eso es correcto.

También, cualquier otro comentario sobre la calidad (o falta de ella) en este código sería apreciado:)

 25
Author: Billy ONeal, 2011-02-07

4 answers

La sugerencia de tipo correcta es callable, que ha estado disponible en p. ej. PhpStorm durante mucho tiempo, y es parte de PSR-5 que actualmente está bajo especificación.

(Me sorprende que nadie más haya mencionado callable, no es nada nuevo y se ha utilizado en todas partes durante años - que yo sepa, callback no es y nunca fue un pseudo-tipo PHP definido )

Tenga en cuenta que callable no solo incluye cierres, sino también devoluciones de llamada PHP de la "vieja escuela", por ejemplo, array($object, 'methodName') o array('ClassName', 'methodName') e incluso 'function_name' - to maximice la utilidad de su API, debe cubrir todos esos casos de uso, lo cual es bastante fácil, ya que tanto call_user_func como call_user_func_array soportan las cuatro variedades de callables: function-name como string, object/method-name, class/method-name y closure.

 33
Author: mindplay.dk,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2016-09-02 19:01:52

"callback" funciona como un tipo de datos válido en phpDocumentor... Acabo de verificarlo... usando PHP 5.2.4, al menos. Es factible que los" tipos de datos válidos " dependan de la versión de PHP con la que ejecute phpDocumentor.

 6
Author: ashnazg,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2011-02-07 19:19:58

PHPDoc realmente no especifica cuáles son los tipos de variables aceptados, solo que deberían ser los nombres de tipos de variables php válidos. En este caso "callback" sería correcto. Ese es el nombre del pseudo-tipo en PHP.

 1
Author: Lèse majesté,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2011-02-07 07:46:11

La documentación de la etiqueta @param no parece haber sido actualizada en eones, por lo que no dice nada sobre cierres o incluso devoluciones de llamada hechas con create_function().

Si phpDocumentor se niega a reconocer callback como un tipo de datos, tendrá que ir con mixed.

 0
Author: BoltClock,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2011-02-07 07:33:35