PHPDoc Type Hinting for Arrays of Objects
When defining member variables in PHP, standard documentation practices often rely on the @var tag to signal intent to static analysis tools and IDEs. A simple instance is straightforward: declaring a private property as an object allows the editor to infer available methods and properties immediately.
class Test
{
/** @var SomeObj */
private $someObjInstance;
}
This works as expected within the context of PHPDoc standards. The parser reads the annotation, understands that $someObjInstance holds a reference to SomeObj, and populates its autocomplete engine accordingly. However, developers frequently encounter a gap in this workflow when dealing with collections. Attempting to extend this logic to arrays often leads to syntax confusion or incorrect hints during iteration.
The core issue arises from the syntax of the @var tag itself. While modern PHPDoc standards support generic type declarations for interfaces like Iterator, simply writing @var array(SomeObj) is technically invalid in most static analysis contexts, including tools powered by PHPSpec or standard IDEs relying on JSDoc-derived parsers. The parser expects a specific format that aligns with how the underlying language defines generic constraints, which differs slightly from standard PHP syntax.
To correctly hint at an array of objects, you must specify the element type within square brackets rather than parentheses. The correct annotation syntax for an array of SomeObj instances is:
class Test
{
/** @var SomeObj[] */
private $someObjInstances;
}
Here, the double brackets [] explicitly denote that the variable contains zero or more elements of type SomeObj. This syntax allows the IDE to recognize that when you iterate over $someObjInstances, the loop variable will be inferred as an instance of SomeObj. If you attempt to use a single bracket [ without the second, or rely on parentheses, the static analyzer may default to treating the value as a generic mixed array or fail to provide specific type hints entirely.
The distinction becomes critical when performing operations that rely on type narrowing. Consider a scenario where you retrieve this collection and need to access properties of the contained objects:
$test = new Test();
// $items is inferred as SomeObj[] due to the @var hint above
foreach ($test->someObjInstances as $item) {
// IDE now knows $item is a SomeObj
}
If the annotation was malformed or missing, the IDE would treat $item as mixed, forcing you to manually cast it or suppress warnings before accessing specific properties. By adhering to the SomeObj[] format, you maintain the flow of type information through your codebase without needing runtime reflection or explicit casting in every loop.
It is worth noting that while PHP 7+ introduced native return types and property declarations for arrays (e.g., private array $someObjInstances;), these do not always fully bridge the gap to static analysis tools without the accompanying DocBlock. The combination of the native type declaration and the specific @var SomeObj[] annotation ensures maximum compatibility across different development environments. Always verify that your target IDE supports this specific bracket syntax, as legacy parsers might misinterpret it if they expect older JSDoc-style generics.
