我什么时候应该在PHPDoc类型提示和docblocks中使用NULL？

Question

我很困惑何时在使用nullPHPDoc描述变量时使用as作为类型.类型提示是否应该描述外部呼叫者预期和遵守的希望和期望,或者他们是否应该记录变量的所有可能类型,即使希望它在实践中是一种非常特定的类型？

示例1:默认值.以下函数仅需要非空值.但是,如果没有传递任何值,则默认为null并明确检查该值作为确定是否传递任何内容的方法,并为该情况返回特殊值.希望没有外部调用者将传递除整数之外的任何内容.应该null在@param下面的类型中使用,还是应该只指定,int因为如果传递任何东西,我们想要传递的是什么？

/**
 * @param int|null $bar
 */
function foo($bar = null) {
  if(is_null($bar)) { 
    return 'ABC';
  }

  return doSomething($bar);
}

示例2:实例属性.我们只想要$ bar来包含整数.也就是说,如果没有为bar设置任何内容,则此实例属性的默认PHP值为null.我是否需要考虑使用$ bar的每个地方,可能的null类型如下所示？

class Foo {
  /**
   * @var int|null
   */
  public $bar;

  /**
   * @param int|null $bar
   */
  public setBar( $bar) {
    $this->bar = $bar;
  }

  /**
   * @return int|null
   */
  public function getBar() {
    return $this->bar;
  }
}

基本上我发现自己几乎每个人都乱扔垃圾@param并@var声明,|null因为从技术上来说它可能就是那个价值.但在实践中它不应该.我是否应该期望我的几乎所有类型都包含null或假设的可能性,我应该避免指定它,除非我期望null明确设置或接收值？

Answer 1

在实践中,我倾向于让param标签只列出你想传入的内容.但是,对于返回标签,你确实需要列出可能返回的每种类型.这就是为什么我对这两者的不同之处.

由于PHP没有强类型,即使你说"只传入一个int",你的方法仍然需要确保它不会传递意外的东西.只是因为方法代码试图处理接收其他类型,你不希望你的文档告诉你的用户"确定,你可以传递给我一个NULL,我会为你做一些事情".你希望你的文档说"给我一个int,期间".

在考虑返回值时,您的用户确实需要知道可能从您的方法返回的每种潜在返回类型,因为他们确实需要在他们的代码中覆盖他们的基础来处理您的方法可能返回的所有类型.

Answer 2

是的，根据 PHPDoc 标准，您应该在所有地方都包含 null（当然，如果适用的话）

请参阅此处：http ://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

数据类型应该是有效的 PHP 类型（int、string、bool 等）、对象类型的类名，或者只是“混合”。此外，您可以通过使用管道分隔单个参数来列出多个数据类型（例如“@param int|string $p1”）。您可以记录列出的参数或任何将由标准 PHP 函数 func_num_args()/get_func_arg() 解析的可选参数。func_get_arg() 列出的参数的推荐名称格式为： $paramname 如果只有一个参数 $paramname,... 如果参数数量不受限制