可迭代对象的正确 phpdoc 注释？答案

【问题标题】：Proper phpdoc comment for iteratable object?可迭代对象的正确 phpdoc 注释？
【发布时间】：2014-04-11 21:50:36
【问题描述】：

我在尝试为以下代码示例获取正确的自动完成时遇到了一点问题。我在 Win7 机器上使用 PHPStorm 7。

首先只是一个简单的类。

/**
 * Class myObject
 */
class myObject
{
    /**
     * some method
     */
    public function myMethod()
    {
        // do something
    }
}

这是一个集合类，可以包含前一个类的多个实例，并实现IteratorAggregate接口。

/**
 * Class myCollection
 */
class myCollection implements IteratorAggregate
{
    /**
     * @var myObject[]
     */
    protected $_objects = array();


    /**
     * @param myObject $object
     * @return myCollection
     */
    public function add(myObject $object)
    {
        $this->_objects[] = $object;

        return $this;
    }


    /**
     * @return ArrayIterator
     */
    public function getIterator()
    {
        return new ArrayIterator($this->_objects);
    }
}

这是代码示例。

$collection = new myCollection;

$collection->add(new myObject);
$collection->add(new myObject);

foreach ($collection as $object) {
    $object->myMethod(); // gets no autocompletion
}

您可能已经猜到（并在示例中读到）myMethod() 调用不会自动完成，而是在代码分析中列出。我发现的唯一方法是为$object 添加评论块，说实话，我觉得这非常烦人。

/** @var $object myObject */
foreach ($collection as $object) {
    $object->myMethod(); // gets autocompletion now, but sucks
}

那么，关于如何解决这个问题的任何想法或基础知识？

【问题讨论】：

也许是因为 ArrayIterator 的返回值是混合的，但我不确定 PHPStorm 是否可以处理迭代值。尝试创建一个自己的 Iterator 来返回您的对象或接口，并查看 IDE 是否可以处理这个问题。最后尝试自己的迭代器可能是项目的开销，所以也许@var 应该没问题。

标签： php interface iterator aggregate phpdoc

【解决方案1】：

/**
 * @return ArrayIterator|myObject[]
 */
public function getIterator()
{
    return new ArrayIterator($this->_objects);
}

对于扩展类（基类在上面）：

/**
 * @method myObject[] getIterator()
 */
class ExtendedClass extends BaseCollection
{
}

或

/**
 * @method iterable<myObject> getIterator()
 */
class ExtendedClass extends BaseCollection
{
}

我认为这将是处理此类案件的最佳方式。至少它适用于 PHPStorm

【讨论】：

【解决方案2】：

你的

/** @var $object myObject */

block 确实是实现此目的的正确方法。您期望完成工作的语法，

/** * @var myObject[] */

不是标准的 phpdoc 表示法，尽管它是非正式使用的，并且正在努力进行标准化。在这种标准化确实发生之前，识别它的 IDE 可能会成败。实际上，您的 $object 本地 var 块的 IDE 覆盖率也是偶然的。

【讨论】：

【解决方案3】：

在您的myCollection 类中，覆盖current()，如下所示：

/** @return myObject */
public function current() {
    return parent::current();
}

【讨论】：

【解决方案4】：

可能的解决方法（也很丑陋）是创建静态“构造函数”，它将返回 myObject。至少它在日食中有效。如果您也想查看收集方法，只需添加 myCollection 以返回为“@return myObject[]|myCollection”

class myCollection implements \IteratorAggregate
{
    /**
     * @return myObject[]
     */
    public function create()
    {
        return new static();
    }
}

【讨论】：