A

15

463

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.

Albite answered 22/4, 2009 at 18:29 Comment(2)

There's some reference in this Netbeans 6.8 dev blog that the IDE is now smart enough to deduce the type of array members: blogs.sun.com/netbeansphp/entry/php_templates_improved – Sacaton 17/10, 2009 at 9:16

@therefromhere: your link is broken. I think the new URL is: blogs.oracle.com/netbeansphp/entry/php_templates_improved – Cowley 16/10, 2012 at 21:30

W

385

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.

Workaday answered 22/4, 2009 at 19:28 Comment(13)

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. :( – Albite 22/4, 2009 at 19:43

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). – Sacaton 30/9, 2009 at 11:31

Works a treat in NetBeans 6.8+. $Obj-> then ctrl-space brings up the expect list of properties and methods. – Exhibitive 7/5, 2010 at 19:58

Note in Netbeans 7, seems to be important you only have one asterisk — /** @var $Obj Test */ doesn't work. – Tierell 13/6, 2011 at 14:58

@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. – Cowley 16/10, 2012 at 21:39

@Cowley I'm not saying you're incorrect, but can you find a reference for this? I can only find documentation that describes @var as valid for describing class variables. I assumed that using @var elsewhere was a useful but non-standard extension, hence the single *. – Tierell 17/10, 2012 at 17:11

This solves problem but it is not good for clean code. I think we have to remove /* @var $Obj Test */ after we finish our work. Do you agree with me? – Libbylibeccio 19/11, 2012 at 13:9

As a note, this apparently doesn't work with abstract classes. So even though my array is ONLY guaranteed to be filled with subclasses of Foo, I have to use an example from one of the children to make it work. – Chalcocite 13/1, 2013 at 22:32

It works for me, but why is the type written after the variable name? Usually it's the other way... – Volding 9/8, 2013 at 21:41

/** @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. – Eno 29/11, 2013 at 8:40

I have to agree with Thom Porter. Indeed, this syntax is supported by phpDocumentor. See phpdoc.org/docs/latest/guides/types.html#arrays and another topic on the same subject #9132562 ! – Adal 22/8, 2014 at 8:0

@var User[] is the answer – Spaniel 10/11, 2015 at 19:46

@Workaday - How can we throw exceptions for type mismatch? – Humfrid 8/6, 2019 at 5:27

K

947

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[]

Keto answered 19/11, 2009 at 13:50 Comment(17)

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 – Vambrace 7/10, 2010 at 19:53

This doesn't work in Netbeans, I am disappointed. Jetbrains make some very nice tools. – Far 30/8, 2011 at 0:0

Thank you! I was trying to figure out the proper syntax in PhpStorm. Knew they would have something. I would have found array<SomeObj> more intuitive. But I guess that's from my C++/C# background (template vars). – Maxwell 2/12, 2011 at 23:16

Can we make the annotation compatible with NetBeans using /** @var SomeObj[]|array */ ? – Ramsgate 13/1, 2012 at 18:56

@Ramsgate @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) – Sacaton 20/1, 2012 at 22:15

This is fully working in the latest nightly builds of Netbeans now, should be included in the 7.2 release. – Sacaton 22/4, 2012 at 3:15

Works in NuSphere's PhpED. – Vow 30/6, 2013 at 8:48

I have a program that builds out basic MVC files for me based on database structure, and from the start I had it including a doc-block comments on the view files for all of the variables defined. I just updated it to use this AWESOME format of @var Object[] $objects... I LOVE this! Thank you to the JetBrains team, and I thank you to SO for having all the right answers! =) – Between 30/8, 2013 at 9:45

Would be nice to have @var Obj[string] for associative arrays. – Unboned 2/12, 2013 at 5:33

Unfortunately Komodo IDE (as of 8.5) only partially supports it: the [] at the end of the hint makes no difference, komodo thinks that it returns that type (single object). – Depositary 26/2, 2014 at 16:51

Should mention works in intellij ultimate too as well as phpstorm – Cupulate 4/4, 2014 at 10:49

Note that you have to put it here: /** @var EditablePane[] $Panes / public $Panes; Not here: public /* var EditablePane[] $Panes */ $Panes; – Zedoary 15/5, 2014 at 16:48

Works in PHP Tools for Visual Studio as well. – Sportsmanship 21/10, 2014 at 13:28

Doesn't work for me in PhpStorm 8.0.3. If I have @return \namespace\Class[] in my docblock, it doesn't show up in the documentation popup (ctrl+q). – Sunburst 20/5, 2015 at 15:24

You can also combine the [] and | syntaxes to indicate an array of mixed types: /** @var A[]|B[] $Obj */ will indicate $Obj is a mixed array of A and B instances, and when you iterate the array (foreach), PhpStorm (maybe others by now?) will show anything accessible from A and B for the current item. It's a bit confusing, considering the syntax implies an array of A OR an array of B, but it works. – Cadel 8/8, 2016 at 21:37

For arrays that could contain multiple types, phpDocumentor indicates the syntax as (A|B)[], and is supported by PHPStorm. – Infer 16/1, 2017 at 21:46

Sorry, I'm a stickler, people are saying PHPStorm is great, but of course for those working across multiple full stacks at once, such as php/laravel, ruby/rails, Java and Angular JS, IntelliJ is also so great with appropriate plugins installed ;) No need to tie up masses of ram with multiple IDEs such as phpstorm + rubymine + intelliJ etc – Valuation 22/1, 2017 at 23:43

W

385

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