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

phpdocumentor laravel

Question

Tengo un método que extrae un árbol transversal de árbol de preorden modificado de la base de datos, y filtra eso 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 lo que debería ser el PHPDoc para la variable $filter : es una devolución de llamada, que es lo que he indicado, pero no estoy seguro de si eso es correcto.

Además, cualquier otro comentario sobre la calidad (o falta de ella) en este código sería apreciado :)

Answer 1

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

Answer 2

La documentación para la etiqueta @param no parece haberse actualizado en eones, por lo que no dice nada sobre cierres o incluso devoluciones de llamadas realizadas con create_function() .

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

Answer 3

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

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

Tenga en cuenta que la callable incluye no solo 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'' - para maximizar la utilidad de su API, debe cubrir todos esos casos de uso, lo cual es bastante fácil, ya que tanto call_user_func y call_user_func compatibles con las cuatro variedades de callables: nombre de función como cadena, nombre de objeto / método, nombre de clase / método y cierre.

Answer 4

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