443

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

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

这很有效，直到我需要对一组对象做同样的事情，以便以后在遍历这些对象时能够获得正确的提示。

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

4

14 回答 14

919

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

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

phpdoc文档推荐这种方法：

指定包含单个类型，类型定义通知读者每个数组元素的类型。然后，只期望一个 Type 作为给定数组的元素。

例子：@return int[]

于 2009-11-19T13:50:37.600 回答
379

采用：

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

于 2009-04-22T19:28:04.433 回答
60

Netbeans 提示：

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

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

当您完成$this->...

于 2015-05-02T06:38:31.057 回答
32

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

$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因此，没有必要在内部使用声明。

于 2013-01-01T13:16:13.470 回答
32

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 样式的集合表示法是另一个问题。

从我对这个问题的回答。

于 2016-09-09T00:02:44.453 回答
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 中启用代码完成。好的。下一步：

使用 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 上认识我和他。

于 2012-10-16T23:32:54.327 回答
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!
}

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

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

于 2013-02-06T14:01:12.103 回答
5

array[type]在 Zend Studio 中使用。

在 Zend Studio 中，array[MyClass]甚至array[int]可以array[array[MyClass]]很好地工作。

于 2014-04-14T23:18:31.977 回答
5

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

繁荣！不需要/** @var SomeObj[] $collectionObj */over 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-methods 是在Abstract-collection 类中实现的，我不知道最终将哪种实体存储在集合中。

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

例子：

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 支持。试试你的，在评论中发布结果！

于 2014-10-30T03:56:29.610 回答
3

我知道我迟到了，但我最近一直在解决这个问题。我希望有人看到这一点，因为接受的答案虽然正确，但并不是您可以做到这一点的最佳方式。至少不在 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)
于 2016-12-23T00:21:18.220 回答
2

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

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

于 2009-04-22T21:04:10.787 回答
1 
<?php foreach($this->models as /** @var Model_Object_WheelModel */ $model): ?>
    <?php
    // Type hinting now works:
    $model->getImage();
    ?>
<?php endforeach; ?>
于 2010-06-27T21:29:11.443 回答
1

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

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

或者

@var array{name: string, content: string}[] $files
于 2021-11-17T13:00:14.357 回答
-5

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

private $userList = array();
$userList = User::fetchAll(); // now $userList is an array of User objects
foreach ($userList as $user) {
   $user instanceof User;
   echo $user->getName();
}
于 2010-01-13T10:43:15.870 回答