458

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 SomeObjs? @var array is not enough, and @var array(SomeObj) doesn't seem to be valid, for example.

2

15 Answers 15

943

In the PhpStorm IDE from JetBrains, you can use /** @var SomeObj[] */, e.g.:

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

The phpdoc documentation recommends this method:

specified containing a single type, the Type definition informs the reader of the type of each array element. Only one Type is then expected as element for a given array.

Example: @return int[]

17
  • 10
    I just downloaded and have been using phpstorm for the past week. Beats the heck out of Aptana (which is great for being free). This is exactly what I was looking for. Actually, it is the same way you'd do it for JavaScript, I should have guessed Oct 7, 2010 at 19:53
  • 6
    This doesn't work in Netbeans, I am disappointed. Jetbrains make some very nice tools.
    – Benbob
    Aug 30, 2011 at 0:00
  • 1
    Can we make the annotation compatible with NetBeans using /** @var SomeObj[]|array */ ?
    – fishbone
    Jan 13, 2012 at 18:56
  • 11
    @fishbone @Keyo this works in Netbeans now (in 7.1 nightly build at least, maybe earlier), though it seems you need to use a temporary variable (a bug?). Hinting for foreach(getSomeObjects() as $obj) doesn't work, but it does for $objs = getSomeObjects(); foreach($objs as $obj) Jan 20, 2012 at 22:15
  • 2
    Would be nice to have @var Obj[string] for associative arrays.
    – donquixote
    Dec 2, 2013 at 5:33
384

Use:

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

when typehinting inline variables, and

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

for class properties.

Previous answer from '09 when PHPDoc (and IDEs like Zend Studio and Netbeans) didn't have that option:

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.

13
  • 3
    This makes sense but it didn't work for PHPEd 5.2. The only thing I was able to come up with that worked is foreach ($Objs as /** @var Test */$Obj), which is horribly ugly. :( Apr 22, 2009 at 19:43
  • 2
    This works in NetBeans 6.7 (I think it's bugged, since you get a ? for the type when you hit ctrl-space, but it is able autocomplete the object's members/methods). Sep 30, 2009 at 11:31
  • 14
    Note in Netbeans 7, seems to be important you only have one asterisk — /** @var $Obj Test */ doesn't work.
    – contrebis
    Jun 13, 2011 at 14:58
  • 4
    @contrebis: The "@var" is a valid docblock tag. So even if your IDE do not support it within a docblock "/** ... /" and supports "@var" in "/ ...*/" only - please, please do not change your correct docblock. File an issue to the bug tracker of your IDE to make your IDE compliant to standards. Imagine your development team / external developers / community uses different IDEs. Keep it as it is and be prepared for the future. Oct 16, 2012 at 21:39
  • 12
    /** @var TYPE $variable_name */ is the correct syntax; do not reverse the order of type and variable name (as suggested earlier in the comments) as that wont work in all cases.
    – srcspider
    Nov 29, 2013 at 8:40
62

Netbeans hints:

You get code completion on $users[0]-> and for $this-> for an array of User classes.

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

You also can see the type of the array in a list of class members when you do completion of $this->...

4
  • 4
    works in PhpStorm 9 EAP as well: /** * @var UserInterface[] */ var $users = []; // Array of Objs implementing an Interface
    – Ronan
    May 27, 2015 at 8:52
  • I've tried it in NetBeans IDE 8.0.2, but it I get suggestions from class I'm currently in. Jul 24, 2015 at 7:43
  • also works in Eclipse 4.6.3 (idk what version support was introduced, but its working, and its what i'm using now)
    – hanshenrik
    Jun 17, 2017 at 23:39
  • This unfortunately doesn't work after using array_pop() or similar functions for some reason. Seems that Netbeans doesn't realize those functions return a single element of the input array.
    – William W
    Jun 2, 2019 at 5:31
34

PSR-5: PHPDoc proposes a form of Generics-style notation.

Syntax

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

Values in a Collection MAY even be another array and even another Collection.

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

Examples

<?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> */

Note: If you are expecting an IDE to do code assist then it's another question about if the IDE supports PHPDoc Generic-style collections notation.

From my answer to this question.

1
32

To specify a variable is an array of objects:

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

This works in Netbeans 7.2 (I'm using it)

Works also with:

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

Therefore use of declaration inside the foreach is not necessary.

5
  • 2
    This solution is cleaner than the accepted answer in my view, because you can use foreach multiple times and the type hinting will continue to work with out a new /* @var $Obj Test */ annotation each time.
    – Henry
    Nov 4, 2014 at 23:32
  • I see two issues here: 1. proper phpdoc starts with /** 2. The correct format is @var <data-type> <variable-name>
    – Christian
    Feb 28, 2016 at 4:46
  • @Christian 1: the main question isn't phpdoc but typehinting 2: the correct format is not like you say, even according to other answers. In fact, I see 2 issues with your comment, and I'm wondering why you dint make your own answer with the correct format Feb 28, 2016 at 17:50
  • 1. Typehinting works with phpdoc...if you don't use the docblock, your IDE will not try guessing what you wrote in some random comment. 2. The correct format, as some other answers also said is what I specified above; data type before variable name. 3. I didn't write another answer because the question doesn't need another one and I'd rather not just edit your code.
    – Christian
    Feb 28, 2016 at 19:01
  • While this works, the autocomplete (type /**<space> and it will expand to include the next variable name) expects the type before the variable name, so /** @var Needle[] $needles */ (PHPStorm 2021.1) May 11, 2021 at 8:26
11

I prefer to read and write clean code - as outlined in "Clean Code" by Robert C. Martin. When following his credo you should not require the developer (as user of your API) to know the (internal) structure of your array.

The API user may ask: Is that an array with one dimension only? Are the objects spread around on all levels of a multi dimensional array? How many nested loops (foreach, etc.) do i need to access all objects? What type of objects are "stored" in that array?

As you outlined you want to use that array (which contains objects) as a one dimensional array.

As outlined by Nishi you can use:

/**
 * @return SomeObj[]
 */

for that.

But again: be aware - this is not a standard docblock notation. This notation was introduced by some IDE producers.

Okay, okay, as a developer you know that "[]" is tied to an array in PHP. But what do a "something[]" mean in normal PHP context? "[]" means: create new element within "something". The new element could be everything. But what you want to express is: array of objects with the same type and it´s exact type. As you can see, the IDE producer introduces a new context. A new context you had to learn. A new context other PHP developers had to learn (to understand your docblocks). Bad style (!).

Because your array do have one dimension you maybe want to call that "array of objects" a "list". Be aware that "list" has a very special meaning in other programming languages. It would be mutch better to call it "collection" for example.

Remember: you use a programming language that enables you all options of OOP. Use a class instead of an array and make your class traversable like an array. E.g.:

class orderCollection implements ArrayIterator

Or if you want to store the internal objects on different levels within an multi dimensional array/object structure:

class orderCollection implements RecursiveArrayIterator

This solution replaces your array by an object of type "orderCollection", but do not enable code completion within your IDE so far. Okay. Next step:

Implement the methods that are introduced by the interface with docblocks - particular:

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

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

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

Do not forget to use type hinting for:

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

This solution stops introducing a lot of:

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

all over your code files (e.g. within loops), as Zahymaka confirmed with her/his answer. Your API user is not forced to introduce that docblocks, to have code completion. To have @return on only one place reduces the redundancy (@var) as mutch as possible. Sprinkle "docBlocks with @var" would make your code worst readable.

Finaly you are done. Looks hard to achive? Looks like taking a sledgehammer to crack a nut? Not realy, since you are familiar with that interfaces and with clean code. Remember: your source code is written once / read many.

If code completion of your IDE do not work with this approach, switch to a better one (e.g. IntelliJ IDEA, PhpStorm, Netbeans) or file a feature request on the issue tracker of your IDE producer.

Thanks to Christian Weiss (from Germany) for being my trainer and for teaching me such a great stuff. PS: Meet me and him on XING.

5
  • this looks like the "right" way, but i cant get it to work with Netbeans. Made a little example: imgur.com/fJ9Qsro
    – fehrlich
    Nov 11, 2013 at 16:09
  • 2
    Maybe in 2012 this was "not a standard", but now it is described as built-in functionality of phpDoc.
    – Wirone
    Jul 25, 2014 at 8:55
  • @Wirone it looks like phpDocumentor adds this to its manual as a reaction to the ide producers. Even if you have a wide tool support it do not mean that it is best practice. It starts to get SomeObj[] spread around in more and more projects, similar to require, require_once, include and include_once did years ago. With autoloading the appearance of that statements drops below 5%. Hopefully SomeObj[] drops to the same rate within the next 2 years in favor to the approach above. Jul 28, 2014 at 13:12
  • 1
    I don't understand why? This is very simple and clear notation. When you see SomeObj[] you know it's an two-dimensional array of SomeObj instances and then you know what to do with it. I don't think it does not follow "clean code" credo.
    – Wirone
    Jul 29, 2014 at 8:39
  • This should be the answer. Not all IDE support approach with @return <className> for current() and all guys, though. PhpStorm supports so it helped me a lot. Thanks mate!
    – Pavel
    Oct 30, 2014 at 3:33
8

if you use PHPStorm 2021.2+ you also can use this syntax (Array shapes):

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

or

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

In NetBeans 7.0 (may be lower too) you could declare the the return type "array with Text objects " just as @return Text and the code hinting will work:

Edit: updated the example with @Bob Fanger suggestion

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

and just use it:

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

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

It is not perfect but it is better then just to leave it just "mixed", which brings no value.

CONS is you are allowed to tread the array as Text Object which will throw errors.

2
  • 1
    I use "@return array|Test Some description." which triggers the same behavior but is a little more explanatory.
    – Bob Fanger
    Mar 26, 2013 at 6:53
  • 2
    This is a workaround, not a solution. What you are saying here is "this function may return an object of type 'Test', OR an array". It however doesn't technically tell you anything about what might be in the array.
    – Byson
    Sep 21, 2015 at 15:43
5

Use array[type] in Zend Studio.

In Zend Studio, array[MyClass] or array[int] or even array[array[MyClass]] work great.

0
5

As DanielaWaranie mentioned in her answer - there is a way to specify the type of $item when you iterating over $items in $collectionObject: Add @return MyEntitiesClassName to current() and rest of the Iterator and ArrayAccess-methods which return values.

Boom! No need in /** @var SomeObj[] $collectionObj */ over foreach, and works right with collection object, no need to return collection with specific method described as @return SomeObj[].

I suspect not all IDE support it but it works perfectly fine in PhpStorm, which makes me happier.

Example:

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
}

What useful i was going to add posting this answer

In my case current() and rest of interface-methods are implemented in Abstract-collection class and I do not know what kind of entities will eventually be stored in collection.

So here is the trick: Do not specify return type in abstract class, instead use PhpDoc instuction @method in description of specific collection class.

Example:

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...

}

Now, usage of classes:

$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();
}

Once again: I suspect not all IDE support it, but PhpStorm does. Try yours, post in comment the results!

2
  • Voucher for pushing it that far, but unfortunately I still can resolve myself to specialize a collection to replace good old java generic types.... yuck'
    – Sebas
    Feb 11, 2016 at 5:42
  • Thank you. How can you typehint a static method? Sep 26, 2018 at 1:36
3

I know I'm late to the party, but I've been working on this problem recently. I hope someone sees this because the accepted answer, although correct, is not the best way you can do this. Not in PHPStorm at least, I haven't tested NetBeans though.

The best way involves extending the ArrayIterator class rather than using native array types. This allows you to type hint at a class-level rather than at an instance-level, meaning you only have to PHPDoc once, not throughout your code (which is not only messy and violates DRY, but can also be problematic when it comes to refactoring - PHPStorm has a habit of missing PHPDoc when refactoring)

See code below:

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();

The key here is the PHPDoc @method MyObj current() overriding the return type inherited from ArrayIterator (which is mixed). The inclusion of this PHPDoc means that when we iterate over the class properties using foreach($this as $myObj), we then get code completion when referring to the variable $myObj->...

To me, this is the neatest way to achieve this (at least until PHP introduces Typed Arrays, if they ever do), as we're declaring the iterator type in the iterable class, not on instances of the class scattered throughout the code.

I haven't shown here the complete solution for extending ArrayIterator, so if you use this technique, you may also want to:

  • Include other class-level PHPDoc as required, for methods such as offsetGet($index) and next()
  • Move the sanity check is_a($object, MyObj::class) from the constructor into a private method
  • Call this (now private) sanity check from method overrides such as offsetSet($index, $newval) and append($value)
0
2

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.

2
  • 5
    One of the things that I love about C/C++ is that it actually keeps track of types down to this level. That would be a very pleasant slope to slip down.
    – Brilliand
    May 2, 2011 at 20:58
  • 2
    Is supported by Netbeans 7.2 (at least that's the version I use), but with a little ajustment namely: /* @var $foo Foo[] */. Just wrote an answer below about it. This can also be used inside foreach(){} loops Jan 1, 2013 at 13:20
2

Here is yet another method of type hinting the structure of an array (Obligatory XKCD: https://xkcd.com/927/).

In my case I sometimes need to describe an argument or return type which is an array of arrays of objects, or even an array of objects with string keys (associative array). PHPStorm provides this ability because it uses Psalm which is a PHP static analysis tool. According to psalm docs on array types, you can do something like this for generic arrays:

/** @return array<TKey, TValue> */

Based on this, I have used it successfully to describe an array of arrays of objects like this:

/** @return array<int, array<int, ObjectClass>> */

or an array of objects with string keys:

/** @return array<string, ObjectClass> */

The options are endless.

1
<?php foreach($this->models as /** @var Model_Object_WheelModel */ $model): ?>
    <?php
    // Type hinting now works:
    $model->getImage();
    ?>
<?php endforeach; ?>
2
-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();
}
4
  • 11
    only problem is that introduces additional code to be executed, which is purely used by your IDE only. It's much better to define type hinting within the comments instead.
    – Ben Rowe
    Jan 28, 2010 at 6:18
  • 1
    Wow this works great. You would end up with additional code but it seems to be harmless. I'm going to start doing: $x instanceof Y; // typehint
    – Igor Nadj
    Sep 5, 2010 at 23:46
  • 3
    Switch to an IDE that gives you code completion based on docblocks or inspections. If you do not want to switch your IDE file a feature request on the issue tracker of your IDE. Oct 16, 2012 at 21:47
  • 1
    If this throws an exception if the type isn't correct, it can be useful for runtime type checking. If...
    – lilbyrdie
    Sep 5, 2014 at 14:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.