使用PHP7时,是否需要使用PHPDoc记录方法?

时间:2017-04-30 20:12:05

标签: php php-7 phpdoc

在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的帮助下为我和我的同事保持方法的一致性。

1 个答案:

答案 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()返回truefalse,其他任何内容,PHP都会尝试将返回值转换为该类型或抛出致命错误。 string的typehint $text也是如此。第一个参数必须是string类型的值,否则PHP会尝试将其强制转换为字符串,否则将抛出致命错误

@return bool@param string根本不执行任何操作,只是说预期收益为truefalse

采用以下示例:

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。