En PHP7, cuando un método establece un tipo de parámetro y tipo de resultado dado, ¿es necesario documentarlos nuevamente en el PHPDoc?
Ya que
function foo(string $text): bool { return true; }Es equivalente a
/** * @param string $text * @return bool */ function foo($text) { return true; }¿Es necesario duplicar estas informaciones?
/** * @param string $text * @return bool */ function foo(string $text): bool { return true; }Editar: no uso PHPDoc para generar la documentación de mi código, sino para mantener la coherencia en los métodos para mí y mis compañeros de trabajo con la ayuda de PHPStorm.
El docblock es algo que un codificador puede usar para explicar lo que hace una función, será ignorado por el analizador de PHP (ver Editar a continuación), ya que es solo un comentario, es una buena práctica colocar un docblock encima de cada función y método, porque cuando alguien (o usted) lee el código, es más fácil ver lo que hace la función.
Un IDE generalmente usa el docblock para autocompletar, sin embargo, el docblock será anulado por la string y :bool cuando el bloque no coincida con el código.
Sin embargo
function foo(string $text): bool { return true; }NO es equivalente a
/** * @param string $text * @return bool */ function foo($text) { return true; } El :bool en el primer ejemplo impone que foo() devuelva true o false , cualquier otra cosa y PHP intentará convertir el retorno a ese tipo o arrojar un error fatal. Es lo mismo con la string typehint para $text . El primer parámetro debe ser un valor de tipo cadena; de lo contrario, PHP intenta convertirlo en una cadena o se generará un error fatal.
La cadena @return bool y @param string no impone nada en absoluto, solo dice que el retorno esperado es true o false
Tome el siguiente ejemplo:
function foo(string $a) :bool { var_dump($a); // string '10' return "string"; } var_dump(foo(10)); // bool true No hay problemas allí, PHP puede convertir 10 en una cadena y "string" es true . Sin embargo, hay un problema con lo siguiente
function foo(PDO $a) :bool { var_dump($a); return "string"; } var_dump(foo(10)); // fatal error, 10 is not PDO and can not be cast to PDOEl uso del docblock hará que el último funcione (probablemente se encuentre con otros problemas más adelante porque probablemente esté tratando de hacer algo con un objeto PDO)
Nota: PHP aún no tiene soporte para tipos mixtos (es decir, cadena | matriz) que aún debe realizarse especificándolo en un docblock
EDITAR:
Como @inwerpsel señaló en los comentarios, mi afirmación de que el analizador de PHP ignora un docblock es incorrecta. ReflectionClass puede leer un docblock durante el tiempo de ejecución.