Как сделать объекты из массивов в PHP с подсказками?

Когда надоело запоминать ключи массивов и хочется пользоваться подсказками любимого редактора кода на помощь приходит PHPDoc и немного смекалки.

Недавно я очень близко познакомился с TypeScript и познал всю прелесть строгой типизации. Как же это приятно, когда редактор кода подсказывает тебе какие поля есть в объекте и что ты с ними можешь сделать!

В чем проблема?

Я работаю с CMS Битрикс и приходится иметь дело с массивами разной формы и содержания, запоминать все ключи или искать их в документации. Это занимает драгоценное время.

Решение:

Первым делом на ум приходит использовать PHPDoc, но тут появляется проблема:

/**  * int[]  * array  * array<string>  */

Нельзя прописать многомерный массив так, чтобы подсказывал редактор кода. Все найденные мной варианты не работают в VSCode и PhpStorm.

Недолго погуглив я нашёл вариант, который заработал только в VSCode.

/**  * @var array $arr $arr  * @var array $arr['fields']  * @var array $arr['fields']['fieldName']  * @var array $arr['fields']['fieldName']['name']  * @var array $arr['fields']['fieldName']['model']  * @var array $arr['fields'][fieldName]['width']  * @var array $arr['fields'][fieldName]['align']  * @var array $arr['fields'][fieldName]['format']  * @var array $arr['fields'][fieldName]['title']  * @var array $arr['fields'][fieldName]['desc']  * @var array $arr['fields'][fieldName]['readonly']  * @var array $arr['fields'][fieldName]['type']  * @var array $arr['fields'][fieldName]['options']  * @var array $arr['fields'][fieldName]['editor']  * @var array $arr['fields'][fieldName]['default']  **/ $arr = [     'fields' => [         'fieldName' => []     ] ];

В таком случае среда подсказывает какой ключ можно выбрать:

Для PhpStorm есть плагин deep-assoc-completion, он требует описания массива в определённом формате:

/**  * @var array $arr = [  *     'fields' => [ // Defines the feilds to be shown by scaffolding  *         $anyKey => [  *             'name' => 'sale', // Overrides the field name (default is the array key)  *             'model' => string, // (optional) Overrides the model if the field is a belongsTo associated value.  *             'width' => '100px', // Defines the width of the field for paginate views. Examples are "100px" or "auto"  *             'align' => 'center', // Alignment types for paginate views (left, right, center)  *             'format' => 'nice', // Formatting options for paginate fields. Options include ('currency','nice','niceShort','timeAgoInWords' or a valid Date() format)  *             'title' => 'Sale', // Changes the field name shown in views.  *             'desc' => 'A deal another person that results in money', // The description shown in edit/create views.  *             'readonly' => false, // True prevents users from changing the value in edit/create forms.  *             'type' => 'password', // Defines the input type used by the Form helper  *             'options' => ['option1', 'option2'], // Defines a list of string options for drop down lists.  *             'editor' => false, // If set to True will show a WYSIWYG editor for this field.  *             'default' => '', // The default value for create forms.  *         ],  *     ],  * ]  */ $arr=[     'fields' => [         '0' => [             'model' => 2         ]     ] ];

В таком случае среда подсказывает ключи:

Остаётся одна проблема, если мы хотим таких подсказок, нам нужно делать подобное описание в каждом файле, где есть наш массив. Особенно актуально для Битрикса.

Моё решение:

Редактор кода хорошо индексирует объекты, так почему бы нам не привести массив к объекту и описать его?! Но как описать объект без класса, ведь PHPDoc в этом тоже помощник?

Мы можем создать класс, в котором опишем все нужные нам поля. И вот наш редактор уже подсказывает нам.

Хорошо, а дальше? Многомерные массивы мы можем описать так же как описываем интерфейсы в TS. Либо выносим вложенный массив в отдельный класс:

Либо прописываем в конструкторе текущего класса:

Обратите внимание, конструктор делаем приватным, чтобы нам не мешался, а вложенному полю обязательно создаём описание. Но PHPStorm его не поймёт.

Резюме

Вариант конечно запарный, но люди, пишущие на TS и так это уже давно делают. Если есть вариант получше, буду рад рассмотреть. И самое главное, смысл не в том, что так надо делать всегда, а в том, что если других вариантов нет (ограничены по времени и т.д. и т.п.), то можно применить эту технологию.