How To Type Hint An Array Of Objects In PHPDoc?

Using Square Bracket Notation

Square bracket notation is a good way to type hint arrays of objects in PHPDoc. The basic syntax uses the object type followed by square brackets:

/** @var User[] */
private $users;

/**
 * @param Product[] $products
 * @return Order[] 
 */
public function processProducts(array $products) {
    // Function implementation
}

This notation works for simple arrays where all elements are of the same object type. It gives information to IDEs and other developers about the array contents.

Benefits of square bracket notation:

• Wide IDE support
• Clear syntax
• Works with code analysis tools
• Supports autocompletion features

/** @var (User|Customer)[] */
private $accounts;

Using Generic Array Syntax

The generic array syntax uses the array keyword with angle brackets to specify the type:

/** @var array<Customer> */
private $customers;

/**
 * @var array<int,Product>
 */
private $productsByIndex;

This method helps you specify key types or work with complex array structures. The syntax lets you define both key and value types:

/**
 * @param array<string,OrderItem> $items
 */
public function processItems(array $items) {
    // Function implementation
}

Advantages of generic array syntax:

• Lets you specify key type
• Supports nested structures
• Works with modern static analysis tools

Limits:

• Not all IDEs support this syntax
• Longer than square bracket notation
• May need extra configuration in some tools

Mixed Type Arrays

PHPDoc supports ways to handle arrays with multiple object types. Here's how to document arrays that contain different object types:

/** @var (User|Customer)[] $mixedUsers */
private $mixedUsers;

/** @var array<int, Book|Magazine> $publications */
private $publications;

// If most items are Products, list Product first
/** @var array<int, Product|Service> $items */
private $items;

Documentation tips for mixed type arrays:

• Write descriptions of each possible type
• Add examples in the documentation
• State when each type appears in the array
• Use simple and logical type combinations

IDE support for mixed type arrays:

• PhpStorm supports all features
• VSCode requires extra extensions
• Some IDEs have limited autocompletion
• Type checking works in most new IDEs

Type Hinting in Different Contexts

Properties:

class Library {
    /** @var Book[] */
    private $books;

    /** @var array<int, Author> */
    protected $authors;
}

Method parameters:

/**
 * @param Article[] $articles
 * @param array<string, Category> $categories
 */
public function sortContent(array $articles, array $categories) {
    // Method implementation
}

Return types:

/**
 * @return Comment[]
 */
public function getComments() {
    // Method implementation
}

/**
 * @return array<int, User>
 */
public function getActiveUsers() {
    // Method implementation
}

Class properties with complex types:

class Store {
    /** @var array<string, Product[]> */
    private $productsByCategory;

    /** @var array<int, Order|Quote> */
    private $transactions;
}