Как правильно указать тип массива объектов в PHPDoc для подсказок IDE?

Основное решение: используйте синтаксис Type[] или array<Type>

Вы абсолютно правы — проблема типизации массивов объектов в PHPDoc стоит очень остро, и от её решения зависит комфорт разработки. Начиная с PHP 7.0 (и особенно в PHP 8+), есть несколько надёжных способов указать тип элементов массива.

1. Классический PHPDoc: @return User[]

Самый распространённый и поддерживаемый всеми IDE способ — использовать квадратные скобки после имени класса:

/**
 * @return User[]
 */
function getUsers(): array {
    return [new User(), new User()];
}

Теперь IDE точно знает, что каждый элемент массива — это объект User, и будет предлагать автодополнение для методов getName() и getEmail(). Этот синтаксис работает для:

• @param User[] $users — массив объектов в параметрах
• @var User[] $users — для переменных внутри кода
• @property User[] $users — для свойств класса

2. Современный синтаксис: array<User> (Generic-стиль)

Начиная с PHP 8.0, вы также можете использовать generic-подобный синтаксис, который предпочитают многие разработчики за его читаемость:

/**
 * @return array<User>
 */
function getUsers(): array {
    return [new User(), new User()];
}

Этот вариант поддерживается всеми современными IDE и более нагляден, особенно когда нужно указать ключи:

/**
 * @return array<int, User>   // Индексированный массив
 * @return array<string, User> // Ассоциативный массив
 */
function getUsersById(): array {
    return [1 => new User(), 2 => new User()];
}

3. Нативная типизация в PHP 8+ (самый надёжный способ)

Если вы используете PHP 8.0 или выше, можно вообще отказаться от PHPDoc и указать тип напрямую в коде:

/**
 * @param User[] $users
 * @return User[]
 */
function processUsers(array $users): array {
    // PHP 8.0+ поддерживает Union Types, но не generic-массивы напрямую
    // Однако IDE всё равно поймёт по PHPDoc
}

К сожалению, на данный момент (PHP 8.3) в синтаксисе PHP нет нативной поддержки generic-типов для массивов, поэтому PHPDoc остаётся основным инструментом. Но есть хорошая новость: в PHP 8.2+ можно использовать атрибуты:

use PhpDoc\Attributes\ReturnType;

#[ReturnType('User[]')]
function getUsers(): array {
    return [new User()];
}

Советы для разных IDE

• PhpStorm: отлично понимает оба синтаксиса (User[] и array<User>). Также поддерживает вложенные типы: array<int, array<User>>
• VS Code с PHP Intelephense: работает аналогично
• NetBeans: лучше используйте User[]

Что делать, если массив может быть пустым?

Используйте префикс с вопросительным знаком или объединение типов:

/**
 * @return User[]|null
 */
function getUsers(): ?array {
    // ...
}

Итог: самый универсальный и проверенный способ — это @return User[]. Он работает везде, понятен всем разработчикам и корректно обрабатывается всеми популярными IDE. Если вы хотите быть более современным — используйте @return array<User>. А в идеале — комбинируйте оба подхода в зависимости от проекта.

class UserCollection {
    /** @var User[] */
    private array $users;

    public function __construct(User ...$users) {
        $this->users = $users;
    }

    public function add(User $user): void {
        $this->users[] = $user;
    }

    /** @return User[] */
    public function toArray(): array {
        return $this->users;
    }

    // Можно добавить итератор для foreach
    public function getIterator(): ArrayIterator {
        return new ArrayIterator($this->users);
    }
}

// Использование
$collection = new UserCollection(new User(), new User());
foreach ($collection as $user) {
    echo $user->getName(); // IDE отлично понимает тип
}