psr - php standard recommendations

Sintaxis de cierre en PHPDoc

Question

No puedo encontrar ninguna documentación sobre el tipo de cierre en PHPDoc. Entonces, mi pregunta es ¿cómo defino el parámetro de los parámetros enviados al cierre y su valor de retorno?

Ejemplo:

¿Cómo describo que la "devolución de llamada" obtendrá un "MyCustomClass", un Número y una Cadena, y devolveré un "MyOtherCustomClass"?

/**
 * @param MyCustomClass $cls
 * @param Closure       $callback this isn''t really explaining what this is
 *
 * @return MyOtherCustomClass
 */
function changer($cls, $callback){

  return $callback($cls, 2, "a string");
}

changer($aCustomeClass, function($cls, $int, $string){
   return new MyOtherCustomClass($cls, $int, $string);
})

O si es posible?

Answer 1

@param callable $callback es de hecho la sintaxis para usar para esa parte. No está limitando ese parámetro a ser un cierre en sí mismo ... cualquier reclamación que se le pase se aceptará en esa implementación. Callable es un "tipo PHP" legal, por lo que phpDocumentor lo acepta como un tipo válido.

En su código de ejemplo, en realidad no hay una razón para suponer que su método changer() devuelve un MyOtherCustomClass() , ya que esto se determina MyOtherCustomClass() por cómo se escribe el cierre más adelante en el uso del changer() . En el mejor de los casos, usted denotaría en un comentario en el uso de changer() que este uso particular de changer() devuelve MyOtherCustomClass , porque es la implementación de ese uso, no la implementación de changer() , lo que devuelve ese tipo específico de objeto.

En cuanto a la documentación de los argumentos que la llamada pasable pasada tiene que "aceptar", supongo que tendrías que hacerlo en la descripción de la etiqueta param. No hay sintaxis para describir tal caso.

Si tuviera que implementar algo de esta manera, impondría una interfaz que todos los reclamos deben devolver explícitamente, y así podría escribir que changer() devuelve esa interfaz. Por supuesto, esto significa que su MyOtherCustomClass debe implementar esa interfaz, pero aún así, me parece que es la única forma de acercarse a "imponer" un tipo de devolución desde changer() .

Answer 2

usar tecnica indirecta

Tu codigo:

/**
 * @param MyCustomClass  $cls
 * @param MyFancyClosure $callback
 *
 * @return MyOtherCustomClass
 */
function changer($cls, $callback){
    return $callback($cls, 2, "a string");
}

changer($aCustomeClass, function($cls, $int, $string){
   return new MyOtherCustomClass($cls, $int, $string);
})

y que proporcionan un código ficticio en alguna parte:

/**
 * this is awesome closure!
 */
class MyFancyClosure {
    /**
     * @param MyCustomClass $cls
     * @param int           $int
     * @param string        $str
     *
     * @return MyOtherCustomClass
     */
    public function __invoke($cls, $int, $str) {}
}

Nota:

1. El cuerpo de la función de __invoke no es obligatorio, así que déjelo en blanco.
2. Use el sufijo "Closure" para el nombre de la clase para aclararlo.