PHP类型提示-代码与注释

Question

PHP 5可以执行一些（有限的）类型提示，但是，在我看来，在现实世界的项目中，类型通常在文档注释中描述。例如，代替此：

/**
 * Test method
 */
function test(SomeType $param1) {
    ...
}

更常见的是

/**
 * Test method
 *
 * @param SomeType param1
 */
function test($param1) {
    ...
}

两种方法的优缺点是什么？如果我认为PhpDoc方法更常见，那是为什么呢？人们为什么不更多地使用内置语言功能？

编辑：第三个选项是将两种方法结合使用：

/**
 * Test method
 *
 * @param SomeType param1
 */
function test(SomeType $param1) {
    ...
}

但是，我个人并不经常使用它（看过Symfony或PHPUnit之类的库），老实说这似乎是在做一些工作而没有太多额外的好处。也许这就是为什么它不经常出现的原因。

Answer 1

首先：PHP 类型提示具有与 PHPDoc 不同的提示能力。差异是（至少）：

• 标量类型。在 PHP 7.1 之前，您无法提示标量类型，但没有什么可以阻止您提示

  /**
   * @param string $param Param description
   */
  

• 暗示数组。在 PHPDoc 中，您可以提示，该参数（或返回值）是某个数组。这将是：

  /**
   * @param ClassName[] $param Param description
   */
  

  其含义是 - 的实例数组ClassName。当涉及到返回类型时，这非常有用（因为 IDE 可能会在该数组的迭代中替换方法，因此，您将知道您是否在做正确的事情）。然而，在 PHP 中你只能将其键入提示为

  function functionName(array $param) { /*...*/ }
  

  所以不可能意识到数组的实际元素是什么。供您参考，有一个相应的RFC，用于将类型提示作为某些元素的数组，目前已被拒绝 - 但将来这种可能性可能会出现在 PHP 中。

但是，另一方面，使用 PHP 类型提示仍然是不同的事情，通常您应该两者都做 - 所以，如果可以在 PHP 中以某种方式提示（如上面的数组示例） - 这样做，并添加 PHPDoc 块。PHP typehint 允许您在语言级别强制执行行为，而 PHPDoc 只是“信息”源，它仅服务于信息目标，并且不能防止传递非法参数类型。

Answer 2

就我个人而言，我会同时使用两者。

第一个选项适合控制将哪些对象传递给该方法。其次通常可以由任何现代 IDE 自动添加，它使您的代码更具可读性。