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

Question

Tengo un método que extrae un árbol transversal de árbol de preordenamiento modificado de la base de datos y lo filtra utilizando 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 el PHPDoc debe ser para la variable $filter - es una devolución de llamada, que es lo que he indicado, pero no estoy seguro 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

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

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

Tenga en cuenta que callable incluye no sólo cierres, pero 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 ambos call_user_func y call_user_func_array admiten las cuatro variedades de callables: nombre-función como cadena, objeto/nombre-método, clase/nombre-método y cierre.

Answer 2

La documentación de la etiqueta @param no parece haber sido actualizado en eones, por lo que doesn' t decir algo sobre cierres o incluso devoluciones de llamada realizadas con create_function().

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

Answer 3

phpDoc realmente no especifica cuáles son los tipos de variables aceptados, solo que deberían ser los nombres de los tipos de variables php válidos. En este caso, la "devolución de llamada" sería correcta. Ese es el nombre del pseudo-tipo en PHP.

Answer 4

"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 ejecuta phpDocumentor.