使用 PHP7 时，是否需要用 PHPDoc 记录方法？

Question

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

Answer 1

文档块是编码人员可以用来解释函数作用的东西，它将被 PHP 解析器忽略（请参阅下面的编辑），因为它只是一个注释，它是一个很好的练习在每个函数和方法上方放置一个文档块，因为当某人（或您）阅读代码时，更容易看到函数的作用。

IDE 通常使用 docblock 来自动完成，但是当块与代码不匹配时，docblock 将被 string 和 :bool 覆盖

然而

function foo(string $text): bool
{
    return true;
}

不等于

/**
 * @param string $text
 * @return bool
 */
function foo($text) {
    return true;
}

第一个示例中的:bool 强制foo() 返回true 或false，否则PHP 将尝试将返回值强制转换为该类型或抛出致命错误。 与$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 在 cmets 中指出的那样，我关于 PHP 解析器忽略 docblock 的说法是不正确的。 ReflectionClass 可以在运行时读取文档块。