Как документировать тип переменной в классе-наследнике в PHP?

Question

[Anton Dyshkant]

Добрый день!

Столкнулся со следующей проблемой.

Есть класс-родитель, например IterableCollection - итератор, который имплементит интерфейс Iterator. В этом классе есть свойство $items, представляющее собой массив каких-то элементов (для класса IterableCollection не имеет значения, что это за элементы).

class IterableCollection implements \Iterator
{
    /**
     * @var mixed[]
     */
    protected $items = [];

    ...
}

Есть класс SomeCollection, который наследует класс IterableCollection. Данный класс является коллекцией объектов класса SomeClass, и в protected-массиве $items лежат элементы класса SomeClass.

Далее я хочу взять какой-то элемент из protected-переменной $items в классе наследнике, но оказывается (ВНЕЗАПНО), что данный элемент отображается phpStorm'ом как mixed.

class SomeCollection extends IterableCollection
{
    public function doSomeWork()
    {
        $this->items[0]->someMethod();
    }
    ...
}

Проблема заключается в том, что когда я вызываю метод someMethod на объекте $this->items[0], то PhpStorm не понимает, что $this->items[0] является объектом класса SomeClass. В этом ничего удивительного нет, потому что это нигде не объявлено.

Вопрос: есть ли способ средствами phpDoc определить, что в классе SomeCollection переменная $items является не mixed[], а SomeClass[]?

Интересует именно способ сделать это средствами phpDoc, а не каким-либо образом переопределяя данное свойство в классе-наследнике.

Спасибо.

UPD.

Если в классе-родителе указать не

/**
     * @var mixed[]
     */
    protected $items = [];
}

а

/**
     * @var array
     */
    protected $items = [];
}

то способ

/**
 * @property SomeClass[] $items
 */
class SomeCollection extends IterableCollection {
    ...
}

действительно работает.

НО.

В таком случае свойство $items считается магическим и публичным, и phpStorm теперь видит его даже вне класса, что есть неправильно.

Answer 1

[Anton Dyshkant]

Очевидно, что при отсутствии в PHP средств обобщённого программирования (генериков) сделать это без костылей (копирование кода, копирование phpDoc'ов, причисление свойства $items к магическим и публичным etc) невозможно.

Answer 2

[mistergonza]

class SomeCollection extends IterableCollection
{
    /**
     * @var SomeClass[] $items
     */
    ...
    public function doSomeWork()
    {
        $this->items[0]->someMethod();
    }
    ...
}

Как-то так

Comments

[Anton Dyshkant]

увы, это не работает

[mistergonza]

Антон Дышкант: ошибочка вышла: вместо var, пишите @property перед объявление класса. Либо в doSomeWork() пишите вставьте phpdoc с var заменив $items на $this->items, но это не лучший вариант.
https://manual.phpdoc.org/HTMLSmartyConverter/PHP/...

Ниже дали правильный ответ.

[Anton Dyshkant]

прошу обратить ваше внимание на заданный мною вопрос:

Вопрос: есть ли способ средствами phpDoc определить, что в классе SomeCollection переменная $items является не mixed[], а SomeClass[]?

Интересует именно способ сделать это средствами phpDoc, а не каким-либо образом переопределяя данное свойство в классе-наследнике.

(выделенные слова - средствами phpDoc).

Также я написал UPD, почему предложенный вами и другими участниками обсуждения вариант не является правильным, по моему мнению.

[mistergonza]

Антон Дышкант: То-есть вы хотите прописать phpDoc'ом в одном месте, чтобы для SomeCollection, SomeCollection2 и т.д., автоматически задавалось соответствие для $items: SomeClass и SomeClass2 соответственно. Если так, то увы, у вас это не получится.

По поводу property: вы указываете /** @ property SomeClass[] $items */ только в одном месте и в классе конкретной коллекции, и везде где используется класс этой коллекции phpstorm будет знать, что в свойстве $items лежит массив объектов SomeClass. Имхо это самый правильный вариант для вашего случая.

[Anton Dyshkant]

Нет, я не хочу, чтобы для SomeCollection и SomeCollection2 был один phpDoc для этого свойства. Пусть их будет два, по одному в каждом классе-наследнике.

По поводу property, повторюсь, что этот тэг предназначен для указания магических (публичных!) свойств класса. Свойство $items не является ни магическим, ни публичным.

Answer 3

[Виталий Хоменко]

Очень внезапно, и правда :)

/**
* @var mixed[]
*/
protected $items = [];

Вот оно:

/**
 * @property SomeClass[] $items
 */
class SomeCollection extends IterableCollection
// ...

Еще вариант:

public function doSomeWork()
{
    /** @var SomeClass[] $items */
    $items =  $this->items;

    $items[0]->someMethod();
}

И еще вариант:

/**
 * @return SomeClass[]
 */
protected function getItems ()
{
    return $this->items;
}
 
public function doSomeWork()
{
    $this->getItems()[0]->someMethod();
}

Comments

[Anton Dyshkant]

отписал UPD в вопросе

[Виталий Хоменко]

Антон Дышкант: Обновил

[Виталий Хоменко]

Антон Дышкант: + еще вариант

[Anton Dyshkant]

Спасибо, но, как я и подчеркнул в вопросе, меня интересует, можно ли это сделать средствами phpDoc (!), а не путём оверрайда.
Вариант с тем, чтобы каждый раз писать /** var SomeClass[] $items */ (как в предпоследнем варианте) - не приемлем в принципе, потому что таких вызовов может быть 100 штук, и 100 раз писать одну и ту же строчку phpDoc является явно не самым оптимальным решением.

[Виталий Хоменко]

Антон Дышкант: Я вам указал все возможные варианты, которые я знаю.

Answer 4

[Пётр Грибанов]

еще вариант с повторным определением свойства с корректный phpDoc

class SomeCollection extends IterableCollection
{
    /**
     * @var SomeClass[]
     */
    protected $items = [];

    public function doSomeWork()
    {
        $this->items[0]->someMethod();
    }
    ...
}