在PHP7中,当方法设置给定的参数类型和结果类型时,是否有必要在PHPDoc中再次记录它们?
自
function foo(string $text): bool
{
return true;
}
相当于
/**
* @param string $text
* @return bool
*/
function foo($text) {
return true;
}
是否有必要复制这些信息?
/**
* @param string $text
* @return bool
*/
function foo(string $text): bool
{
return true;
}
编辑:我不使用PHPDoc来生成我的代码文档,而是在PHPStorm的帮助下为我和我的同事保持方法的一致性。
答案 0 :(得分:14)
docblock是编码人员用来解释函数功能的东西,它会被PHP解析器忽略,因为它只是一个注释,将docblock放在每个函数和方法之上是一个好习惯,因为当某人(或你)阅读代码时,更容易看到该功能的作用。
IDE通常使用docblock进行自动填充,但当块与代码不匹配时,string
和:bool
会覆盖docblock
然而
function foo(string $text): bool
{
return true;
}
不等同于
/**
* @param string $text
* @return bool
*/
function foo($text) {
return true;
}
第一个示例中的:bool
强制foo()
返回true
或false
,其他任何内容,PHP都会尝试将返回值转换为该类型或抛出致命错误。
string
的typehint $text
也是如此。第一个参数必须是string类型的值,否则PHP会尝试将其强制转换为字符串,否则将抛出致命错误
@return bool
和@param string
根本不执行任何操作,只是说预期收益为true
或false
采用以下示例:
function foo(string $a) :bool
{
var_dump($a); // string '10'
return "string";
}
var_dump(foo(10)); // bool true
没有问题,PHP可以将10
转换为字符串,"string"
为true
以下是
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 PDO
使用docblock将使最后一个工作(可能会进一步遇到其他问题,因为您可能正在尝试使用PDO对象执行某些操作)
注意:PHP还没有支持混合类型的类型(即字符串|数组)仍然必须通过在docblock中指定它来完成
修改强>
正如@inwerpsel在评论中指出的那样,我的说法是PHP解析器忽略了一个docblock是不正确的。可以在运行时期间通过ReflectionClass读取docblock。