Doctrine 集合的 Docblocks答案

【问题标题】：Docblocks for Doctrine collectionsDoctrine 集合的 Docblocks
【发布时间】：2011-11-09 21:32:19
【问题描述】：

在 Doctrine 项目的 docblock 注释中，是否有标准的方法来记录 Collection 中的预期实体类？比如：

/**
 * @var Collection<User>
 */
protected $users;

看起来 PHPDoc 现在是 docblock 注释的事实标准，但我找不到任何关于这个用例的提及。

【问题讨论】：

这个问题几乎是 10 年前的事了。今天，OP 的建议对我来说很好，无论是在 PhpStorm 还是在 Psalm 中。诗篇也可能要求添加键类型，因此通常：Collection<int, User>

标签： php doctrine doctrine-orm phpdoc docblocks

【解决方案1】：

我认为User[] 应该可以。不记得我在哪里找到的。

【讨论】：

我在某处也遇到过这种情况，它表示一个数组。但是，它并不强制 Collection 本身的类！

【解决方案2】：

有几种不同的方法可以记录预期变量。查看phpDoc documentation 以获取可用标签的完整列表。

class MyClass
{
    /**
     * Users collection
     * @var \Doctrine\ORM\ArrayCollection
     */
    protected $users;

    /**
     * My method that doesn't do much
     * @param \Doctrine\ORM\ArrayCollection $users
     * @return void
     */
    public function myMethod(\Doctrine\ORM\ArrayCollection $users)
    {
        /** @var \Entities\Users $user */
        $user = current($this->users);
    }
}

【讨论】：

我希望能有更明确和更少重复的东西......如果你有几个涉及$this->users的方法，那意味着很多文档块重复！
ArrayCollection 是一个通用集合，可以采用任何类型的实体（或任何对象）；并且因为它可以包含 anything，集合实体的自动完成功能无法工作。第三种方法应该工作得很好，你只需要在使用它之前检查它是不是假的
另外，如果您要重用$this->users，则将文档块放在protected $users; 减速就足够了。另一方面，您的文档块应该准确地解释您的期望。如果您必须为多种方法重复@param \Doctrine\ORM\ArrayCollection $users，那就这样吧。
谢谢，顺便说一句，使用类型提示时是否必须明确使用@param docblock？我认为 IDE 和 PHPDoc 都可以处理这个问题，并且 @param 更适用于原语，因为类/接口类型提示是在语言中构建的。
IDE 中的类型提示不需要它，但就像我之前所说的那样；你应该记录一切。不正确的文档与根本没有文档一样糟糕，甚至更糟。

【解决方案3】：

这是一个解决方案，可让您在 Collection 方法和您的 objects 方法上都有自动完成功能：

/**
 * @param Collection|User[] $users
 */
public function foo($users)
{
    $users-> // autocompletion on Collection methods works

    foreach ($users as $user) {
        $user-> // autocompletion on User methods work
    }
}

至少在 PhpStorm 中它就像一个魅力。

【讨论】：

不错！现在这个问题解决了，唯一剩下的是一个实际的 typeHint 用于可迭代参数，如数组和 Collection :)
虽然这在 PhpStorm 中有效，但我认为这是一个无效的类型提示，因为它说你可以传入一个用户对象数组，在这种情况下，任何超出魔法迭代的集合方法都将无效。
@Rican7 Collection 实现 ArrayAccess。所以你可以像数组一样使用对象，它会起作用，例如$users[] = new User().
@MatthieuNapoli 对，但这只是一种方式。现在您告诉您的用户他们可以使用数组，但数组不能像集合一样使用。数组没有isEmpty() 方法。即便如此，ArrayAccess 接口也不允许在 array_merge() 这样的数组函数中使用类。
好的，我明白你的意思了。我确实不会将此类型提示用于其他用户将使用的库。但对于我们的团队来说，它确实有效。在 PSR-5 中，可以使用泛型符号，因此更合适：Collection<User>。但是我不确定 PhpStorm 是否容易处理它。