对象数组的PHPDoc类型提示？

在 JetBrains 的 PhpStorm IDE 中，您可以使用 /** @var SomeObj[] */，例如：

/**
 * @return SomeObj[]
 */
function getSomeObjects() {...}

phpdoc documentation 推荐这种方法：

指定包含单个类型，类型定义通知读者每个数组元素的类型。然后，只期望一个 Type 作为给定数组的元素。示例：@return int[]

---

利用：

/* @var $objs Test[] */
foreach ($objs as $obj) {
    // Typehinting will occur after typing $obj->
}

键入提示内联变量时，以及

class A {
    /** @var Test[] */
    private $items;
}

对于类属性。

09 年 PHPDoc（以及 Zend Studio 和 Netbeans 等 IDE）没有该选项时的先前答案：

你能做的最好的就是说，

foreach ($Objs as $Obj)
{
    /* @var $Obj Test */
    // You should be able to get hinting after the preceding line if you type $Obj->
}

我在 Zend Studio 中经常这样做。不知道其他编辑器，但它应该工作。

---

Netbeans 提示：

您在 $users[0]-> 和 $this-> 上为一组用户类获得代码完成。

/**
 * @var User[]
 */
var $users = array();

当您完成 $this->... 时，您还可以在类成员列表中查看数组的类型

---

指定一个变量是一个对象数组：

$needles = getAllNeedles();
/* @var $needles Needle[] */
$needles[1]->...                        //codehinting works

这适用于 Netbeans 7.2（我正在使用它）

也适用于：

$needles = getAllNeedles();
/* @var $needles Needle[] */
foreach ($needles as $needle) {
    $needle->...                        //codehinting works
}

因此，没有必要在 foreach 中使用声明。

---

PSR-5: PHPDoc 提出了一种泛型风格的表示法。

句法

Type[]
Type<Type>
Type<Type[, Type]...>
Type<Type[|Type]...>

集合中的值甚至可能是另一个数组甚至另一个集合。

Type<Type<Type>>
Type<Type<Type[, Type]...>>
Type<Type<Type[|Type]...>>

例子

<?php

$x = [new Name()];
/* @var $x Name[] */

$y = new Collection([new Name()]);
/* @var $y Collection<Name> */

$a = new Collection(); 
$a[] = new Model_User(); 
$a->resetChanges(); 
$a[0]->name = "George"; 
$a->echoChanges();
/* @var $a Collection<Model_User> */

注意：如果您希望 IDE 进行代码辅助，那么 IDE 是否支持 PHPDoc Generic 样式的集合表示法是另一个问题。

从我对 this question 的回答。

---

我更喜欢阅读和编写干净的代码 - 正如 Robert C. Martin 的“干净代码”中所述。当遵循他的信条时，您不应该要求开发人员（作为您的 API 的用户）知道您的数组的（内部）结构。

API 用户可能会问：这是一个只有一维的数组吗？对象是否分布在多维数组的所有级别上？我需要多少个嵌套循环（foreach 等）才能访问所有对象？该数组中“存储”了哪些类型的对象？

正如您概述的那样，您希望将该数组（包含对象）用作一维数组。

正如 Nishi 所述，您可以使用：

/**
 * @return SomeObj[]
 */

为了那个原因。

但同样：请注意 - 这不是标准的 docblock 表示法。这种表示法是由一些 IDE 生产者引入的。

好的，好的，作为开发人员，您知道“[]”与 PHP 中的数组相关联。但是在普通 PHP 上下文中，“something[]”是什么意思呢？ “[]”表示：在“某物”中创建新元素。新元素可能就是一切。但是您要表达的是：具有相同类型的对象数组并且它的确切类型。如您所见，IDE 生产者引入了一个新的上下文。您必须学习的新环境。其他 PHP 开发人员必须学习的新环境（以了解您的文档块）。糟糕的风格（！）。

因为您的数组确实有一个维度，您可能想将该“对象数组”称为“列表”。请注意，“列表”在其他编程语言中具有非常特殊的含义。例如，将其称为“收藏”会更好。

请记住：您使用的编程语言可以实现 OOP 的所有选项。使用类而不是数组，并使您的类像数组一样可遍历。例如：

class orderCollection implements ArrayIterator

或者，如果您想将内部对象存储在多维数组/对象结构中的不同级别：

class orderCollection implements RecursiveArrayIterator

此解决方案将您的数组替换为“orderCollection”类型的对象，但目前尚未在您的 IDE 中启用代码完成。好的。下一步：

使用 docblocks 实现接口引入的方法 - 特别是：

/**
 * [...]
 * @return Order
 */
orderCollection::current()

/**
 * [...]
 * @return integer E.g. database identifier of the order
 */
orderCollection::key()

/**
 * [...]
 * @return Order
 */
orderCollection::offsetGet()

不要忘记使用类型提示：

orderCollection::append(Order $order)
orderCollection::offsetSet(Order $order)

该解决方案不再引入很多：

/** @var $key ... */
/** @var $value ... */

正如 Zahymaka 用她/他的回答确认的那样，遍布您的代码文件（例如循环内）。您的 API 用户不必引入该文档块来完成代码。让@return 只在一个地方尽可能减少冗余（@var）。撒上“带有@var 的docBlocks”会使你的代码可读性变差。

最后你完成了。看起来很难实现？看起来像拿大锤敲碎坚果？不是真的，因为您熟悉这些接口和干净的代码。请记住：您的源代码编写一次/多次阅读。

如果您的 IDE 的代码完成不适用于这种方法，请切换到更好的方法（例如 IntelliJ IDEA、PhpStorm、Netbeans）或在您的 IDE 生产者的问题跟踪器上提交功能请求。

感谢 Christian Weiss（来自德国）担任我的教练并教给我这么棒的东西。 PS：在 XING 上认识我和他。

---

在 NetBeans 7.0（也可能更低）中，您可以将返回类型“带有文本对象的数组”声明为 @return Text，代码提示将起作用：

编辑：用@Bob Fanger 建议更新了示例

/**
 * get all Tests
 *
 * @return Test|Array $tests
 */
public function getAllTexts(){
    return array(new Test(), new Test());
}

并使用它：

$tests =  $controller->getAllTests();
//$tests->         //codehinting works!
//$tests[0]->      //codehinting works!

foreach($tests as $text){
    //$test->      //codehinting works!
}

它并不完美，但最好只是让它“混合”，这没有任何价值。

缺点是您可以将数组作为文本对象进行处理，这会引发错误。

---

在 Zend Studio 中使用 array[type]。

在 Zend Studio 中，array[MyClass] 或 array[int] 甚至 array[array[MyClass]] 工作得很好。

---

正如 DanielaWaranie 在她的回答中提到的那样 - 当您迭代 $collectionObject 中的 $items 时，有一种方法可以指定 $item 的类型：将 @return MyEntitiesClassName 添加到 current() 以及其余的 Iterator 和 ArrayAccess 方法返回值。

Boom！ 不需要在 /** @var SomeObj[] $collectionObj */ 中超过 foreach，并且可以与集合对象一起使用，无需使用描述为 @return SomeObj[] 的特定方法返回集合。

我怀疑并非所有 IDE 都支持它，但它在 PhpStorm 中运行良好，这让我更开心。

例子：

class MyCollection implements Countable, Iterator, ArrayAccess {

    /**
     * @return User
     */
    public function current() {
        return $this->items[$this->cursor];
    }

    //... implement rest of the required `interface` methods and your custom
}

我要添加发布此答案有什么用

在我的情况下，current() 和其余的 interface-方法在 Abstract-collection 类中实现，我不知道最终将在集合中存储哪种实体。

所以这里是诀窍：不要在抽象类中指定返回类型，而是在特定集合类的描述中使用 PhpDoc 指令 @method。

例子：

class User {

    function printLogin() {
        echo $this->login;
    }

}

abstract class MyCollection implements Countable, Iterator, ArrayAccess {

    protected $items = [];

    public function current() {
        return $this->items[$this->cursor];
    }

    //... implement rest of the required `interface` methods and your custom
    //... abstract methods which will be shared among child-classes
}

/**
 * @method User current()
 * ...rest of methods (for ArrayAccess) if needed
 */
class UserCollection extends MyCollection {

    function add(User $user) {
        $this->items[] = $user;
    }

    // User collection specific methods...

}

现在，类的用法：

$collection = new UserCollection();
$collection->add(new User(1));
$collection->add(new User(2));
$collection->add(new User(3));

foreach ($collection as $user) {
    // IDE should `recognize` method `printLogin()` here!
    $user->printLogin();
}

再一次：我怀疑并非所有 IDE 都支持它，但 PhpStorm 支持。试试你的，在评论中发布结果！

---

如果您使用 PHPStorm 2021.2+，您也可以使用以下语法（数组形状）：

@property array{name: string, content: string}[] $files

或者

@var array{name: string, content: string}[] $files

---

我知道我迟到了，但我最近一直在解决这个问题。我希望有人看到这一点，因为接受的答案虽然正确，但并不是您可以做到这一点的最佳方式。至少不在 PHPStorm 中，不过我还没有测试过 NetBeans。

最好的方法是扩展 ArrayIterator 类，而不是使用原生数组类型。这允许您在类级别而不是实例级别键入提示，这意味着您只需 PHPDoc 一次，而不是在整个代码中（这不仅混乱而且违反 DRY，而且在涉及重构 - PHPStorm 有重构时缺少 PHPDoc 的习惯）

请参见下面的代码：

class MyObj
{
    private $val;
    public function __construct($val) { $this->val = $val; }
    public function getter() { return $this->val; }
}

/**
 * @method MyObj current()
 */
class MyObjCollection extends ArrayIterator
{
    public function __construct(Array $array = [])
    {
        foreach($array as $object)
        {
            if(!is_a($object, MyObj::class))
            {
                throw new Exception('Invalid object passed to ' . __METHOD__ . ', expected type ' . MyObj::class);
            }
        }
        parent::__construct($array);
    }

    public function echoContents()
    {
        foreach($this as $key => $myObj)
        {
            echo $key . ': ' . $myObj->getter() . '<br>';
        }
    }
}

$myObjCollection = new MyObjCollection([
    new MyObj(1),
    new MyObj('foo'),
    new MyObj('blah'),
    new MyObj(23),
    new MyObj(array())
]);

$myObjCollection->echoContents();

这里的关键是 PHPDoc @method MyObj current() 覆盖了从 ArrayIterator 继承的返回类型（即 mixed）。包含这个 PHPDoc 意味着当我们使用 foreach($this as $myObj) 迭代类属性时，我们会在引用变量 $myObj->... 时获得代码完成

对我来说，这是实现这一点的最巧妙的方法（至少在 PHP 引入类型化数组之前，如果他们曾经这样做的话），因为我们在可迭代类中声明迭代器类型，而不是在散布在代码中的类的实例上声明。

我没有在这里展示扩展 ArrayIterator 的完整解决方案，所以如果你使用这种技术，你可能还想：

根据需要包含其他类级别的 PHPDoc，用于 offsetGet($index) 和 next() 等方法

将完整性检查 is_a($object, MyObj::class) 从构造函数移到私有方法中

从 offsetSet($index, $newval) 和 append($value) 等方法覆盖调用这个（现在是私有的）完整性检查

---

问题是 @var 只能表示单一类型 - 不包含复杂的公式。如果您有“Foo 数组”的语法，为什么要停在那里而不添加“数组数组，包含 2 个 Foo 和 3 个 Bar”的语法？我知道元素列表可能比这更通用，但它是一个滑坡。

就个人而言，我有时使用 @var Foo[] 来表示“Foo 的数组”，但 IDE 不支持它。

---

<?php foreach($this->models as /** @var Model_Object_WheelModel */ $model): ?>
    <?php
    // Type hinting now works:
    $model->getImage();
    ?>
<?php endforeach; ?>

---

我发现了一些有效的方法，它可以挽救生命！

private $userList = array();
$userList = User::fetchAll(); // now $userList is an array of User objects
foreach ($userList as $user) {
   $user instanceof User;
   echo $user->getName();
}

---