PHPDoc type hinting for array of objects?

Question

So, in PHPDoc one can specify @var above the member variable declaration to hint at its type. Then an IDE, for ex. PHPEd, will know what type of object it's working with and will be able to provide a code insight for that variable.

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

This works great until I need to do the same to an array of objects to be able to get a proper hint when I iterate through those objects later on.

So, is there a way to declare a PHPDoc tag to specify that the member variable is an array of SomeObj's? @var array is not enough, and @var array(SomeObj) doesn't seem to be valid, for example.

Answer 1

you can use the casting syntax for your variables. to cast a variable into a specific data type, you may use this syntax: (type) value. like this:

$number = '1';
echo (integer)$number + 3;
// output: 4;

if you use this kind of syntax when you are using your array members, you could hope that your IDE supports it. like this

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

I use Netbeans IDE v.6.5.1 and it works for me. although it marks the casting expression an error, and I clear after I wrote my code, but for the time of calling my methods, it will help me.

Answer 2

The best you can do is say,

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

I do that a lot in Zend Studio. Don't know about other editors, but it ought to work.

Answer 3

The problem is that @var can just denote a single type - Not contain a complex formula. If you had a syntax for "array of Foo", why stop there and not add a syntax for "array of array, that contains 2 Foo's and three Bar's"? I understand that a list of elements is perhaps more generic than that, but it's a slippery slope.

Personally, I have some times used @var Foo[] to signify "an array of Foo's", but it's not supported by IDE's.

Answer 4

In Web IDE (PHP edition) from JetBrains, you can use /** @var SomeObj[] */, e.g.:

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

Answer 5

I've found something which is working, it can save lives !

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 6

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