phpDoc表示法，用于指定与参数类型相同的返回类型 [英] phpDoc notation to specify return type identical to parameter type

问题描述

想象一下以下假设的类结构，而不是在所有PHPdoc提示都正确设置的情况下不太常见的情况:

Imagine the following hypothetical class structure, not an all too uncommon scenario with all PHPdoc hinting set up correctly:

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 = [];
}

现在我按如下方式使用此代码:

Now I use this code as follows:

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

在phpStorm中(可能还有其他大多数IDE，因为这很有意义)，第二行会发出警告，指出BaseFilter不包含方法setMinLength.尽管绝对正确，但这是预期的多态行为，充分利用了PHP的后期绑定特性-在像C#这样的语言中，您必须显式地进行转换.因此，我希望phpDoc语法在这里支持某种动态符号，指出addFilter的返回类型与提供的$filter类型相同.

In phpStorm (and probably most other IDEs since it makes sense) the second line produces a warning, stating that BaseFilter does not contain a method setMinLength. While absolutely correct, this is intended polymorphism behaviour, fully utilizing PHP's late binding characteristics - in a language like C# you'd have to upcast explicitly. As such I would expect phpDoc syntax to support some kind of dynamic notation here, stating that the return type for addFilter is identical to the $filter type supplied.

我尝试将其更改为:

@return $filter

但这只是作为对BaseFilter的引用，因此被视为此类，但仍给出警告.

But this just shows up as a reference to BaseFilter and is treated as such, still giving the warning.

是否有某种标准化的方法可以达到这种效果，至少普通的IDE可以理解它?

Is there any standardized way to achieve this effect, in such a way that at least the common IDEs can understand it?

推荐答案

IDE可能在此处执行的最佳操作是，如果您对addFilter()的@return实际上列出了所有可能返回的BaseFilter子级:

Probably the best an IDE could do here would be if your @return on addFilter() actually listed all the possible BaseFilter children that could be returned:

@return BaseFilter|TextFilter|AnotherFilter

此可能会触发您的IDE为所有可能的返回类提供所有可能的方法.这取决于使用的IDE是否知道如何识别可能的返回类型列表.显然，将这​​样的列表放入许多返回标记中，对您而言，这将很繁琐.

This might trigger your IDE into providing all the possible methods for all those possible return classes. It depends on whether or not the IDE in use knows how to recognize such a list of possible return types. Obviously this would get tedious on your part though, putting such a list in many return tags.

我不知道任何IDE会单独查看您的BaseFilter返回类型，生成所有可能的parent + child方法的列表，从而使整个列表可自动自动完成.

I do not know of any IDE that would look at your return type of BaseFilter alone, generate a list of all possible parent+child methods, and thus make that whole list available for autocompletion automagically.

这篇关于phpDoc表示法，用于指定与参数类型相同的返回类型的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！