对象数组的PHPDoc类型提示？

Question

因此，在 PHPDoc 中，可以在成员变量声明上方指定 @var 以提示其类型。然后是一个 IDE，例如。 PHPEd 将知道它正在使用什么类型的对象，并将能够为该变量提供代码洞察力。

<?php
  class Test
  {
    /** @var SomeObj */
    private $someObjInstance;
  }
?>

这很好用，直到我需要对一组对象执行相同的操作才能在以后遍历这些对象时获得正确的提示。

那么，有没有办法声明一个PHPDoc标签来指定成员变量是SomeObjs的数组呢？例如@var 数组是不够的，@var array(SomeObj) 似乎无效。

Answer 1

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

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

或

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

Answer 2

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

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

phpdoc documentation 推荐这种方法：

指定包含单个类型，类型定义通知读者每个数组元素的类型。给定数组的元素只有一个类型。

示例：@return int[]

Answer 3

正如 DanielaWaranie 在她的回答中提到的 - 当您在 $collectionObject 中迭代 $item 时，有一种方法可以指定 $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 支持。试试你的，在评论中发布结果！

Answer 4

用途：

/* @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 中经常这样做。不知道其他编辑器，但它应该可以工作。

Answer 5

在 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!
}

它并不完美，但总比让它“混合”更好，这没有任何价值。

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

Answer 6

我知道我迟到了，但我最近一直在解决这个问题。我希望有人看到这一点，因为接受的答案虽然正确，但 不是 你可以做到这一点的最佳方式。至少不在 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) 等方法覆盖调用这个（现在是私有的）健全性检查

Answer 7

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的回答。

Answer 8

Netbeans 提示：

您可以在 $users[0]-> 和 $this-> 上获得用户类数组的代码完成。

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

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

Answer 9

在 Zend Studio 中使用 array[type]。

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

Answer 10

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

$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 中使用声明。

Answer 11

我更喜欢阅读和编写干净的代码 - 正如 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 中启用代码完成功能。好的。下一步：

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

/**
 * [...]
 * @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 上认识我和他。

Answer 12

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

Answer 13

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

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

Answer 14

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

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