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

在用PHPDoc描述变量时，我不知道何时使用

null

作为类型。类型提示是否应该描述外部调用方预期和遵守的希望和期望，还是应该记录变量的所有可能类型，即使希望是它在实践中将是一种非常具体的类型

示例1：默认值。以下函数只需要非空值。但如果没有传递任何值，它将默认为

null

，并显式检查该值以确定是否传递了任何内容，并为该情况返回一个特殊值。希望没有外部调用程序会传递除整数以外的任何内容。在下面的

@param

类型中应该使用

null

，还是应该只指定

int

，因为如果传递了任何内容，我们希望传递的就是

int

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

  return doSomething($bar);
}

示例2：实例属性。我们只希望$bar包含整数。也就是说，如果没有为bar设置任何内容，那么这个实例属性的默认PHP值为null。我是否需要在每一个使用$bar的地方都考虑到这一点，可能的空类型如下

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

的值？

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

请看这里：

数据类型应该是一个有效的PHP类型（int、string、bool等），一个 对象类型的类名，或简称“混合”。此外，你可以 通过使用分隔符为单个参数列出多个数据类型 管道（例如“@param int | string$p1”）。您可以记录参数 列出或任何将由标准PHP解析的可选参数 函数func\u num\u args（）/get\u func\u arg（）。推荐的名称格式 与func_get_arg（）一起列出的参数是： $paramname（如果只有一个参数） $paramname，。。。如果参数的数量是无限的

---

实际上，我倾向于让param标记只列出您想要传递的内容。然而，对于返回标记，您确实需要列出可能返回的每种类型。这就是为什么我在这两个问题上存在分歧

由于PHP不是强类型的，即使您说“只传入一个int”，您的方法仍然需要确保没有传递意外的消息。仅仅因为方法代码试图处理接收其他类型，您不希望您的文档告诉用户“当然，您可以传递NULL，我会为您做一些事情”。你想让你的文档说“给我一个整数，句号”

---

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

我同意。在“返回”中，指定所有可能的返回值。对于参数，只需指定期望值。如果null或string不是您真正想要的字段，那么不要在文档中将它们列为有效字段，因为php不会对数组和对象以外的任何对象强制执行类型暗示。