用于指定与参数类型相同的返回类型的 phpDoc 符号

Question

想象一下以下假设的类结构，所有 PHPdoc 提示都正确设置的情况并不少见:

class BaseFilter {
  /** ...base methods... */
}

class TextFilter extends BaseFilter {
  public function setMinLength($len)
  {
    /** ...irrelevant */
  }
}

class SomethingWithFilters
{
  /**
   * @param BaseFilter $filter A valid filter to be added.
   * @return BaseFilter The filter that was added for easy chaining
   */
  public function addFilter(BaseFilter $filter)
  {
    $this->filters[] = $filter;
    return $filter;
  }

  /** @var BaseFilter[] A list of filters */
  private $filters = [];
}

现在我使用这段代码如下:

$myClass = new SomethingWithFilters();
$myClass->addFilter(new TextFilter())->setMinLength(8);

在 phpStorm(可能还​​有大多数其他 IDE，因为它有意义)中，第二行产生警告，说明 BaseFilter 不包含方法 setMinLength。虽然绝对正确，但这是有意的多态行为，充分利用了 PHP 的后期绑定(bind)特性——在像 C# 这样的语言中，您必须显式地向上转换。因此，我希望 phpDoc 语法在这里支持某种动态符号，声明 addFilter 的返回类型与提供的 $filter 类型相同。

我尝试将其更改为:

@return $filter

但这只是显示为对 BaseFilter 的引用，并被如此对待，仍然发出警告。

是否有任何标准化的方式来实现这种效果，至少普通的 IDE 可以理解它？

Answer 1

如果 addFilter() 上的 @return 实际上列出了可以返回的所有可能的 BaseFilter 子级，IDE 在这里可以做的最好的事情可能是:

@return BaseFilter|TextFilter|AnotherFilter

这可能触发您的 IDE 为所有那些可能的返回类提供所有可能的方法。这取决于所使用的 IDE 是否知道如何识别此类可能返回类型的列表。显然，将这​​样的列表放在许多返回标记中，这对您来说会很乏味。

我不知道有哪个 IDE 会单独查看您的 BaseFilter 返回类型，生成所有可能的父+子方法的列表，从而使整个列表可用于自动完成自动。