169  /  382
Справочник

Аннотации классов

Просмотров: 45452
Дата последнего изменения: 14.05.2021
Татьяна Старкова
Сложность урока:
4 уровень - сложно, требуется сосредоточиться, внимание деталям и точному следованию инструкции.
1
2
3
4
5
Недоступно в лицензиях:
Ограничений нет

Большая часть методов Объекта и Коллекции - виртуальные, обрабатываются через magic вызов __call. В то же время они сделаны для интуитивно понятных и говорящих именованных методов, и без автокомплита в IDE их ценность резко снижается.

Чтобы IDE все же знала об их существовании и помогала ориентироваться в большом количестве классов и методов, мы сделали для нее специальный служебный файл с аннотациями всех сущностей.

С версии 20.100.0 Главного модуля (main) файл с аннотациями ORM-классов ядра включен в поставку и расположен в /bitrix/modules/main/meta/orm.php.

Для генерации таких аннотаций используется cli-команда orm:annotate:

$ cd bitrix
$ php bitrix.php orm:annotate

Примечание: перед использованием CLI-окружения убедитесь, что установили зависимости проекта через composer.

В процессе выполнения команды производится сканирование модулей, а именно всех файлов из папок bitrix/modules/[module]/lib. Если в файле обнаруживается "маппинг" сущности (класс Table, подкласс Bitrix\Main\ORM\Data\DataManager), то анализируется ее карта (список полей).

Результатом команды является файл (по умолчанию bitrix/modules/orm_annotations.php), который содержит описания классов Объекта и Коллекции сущностей. Также в нем декларируются дубликат класса Table и несколько фактически несуществующих вспомогательных классов, помогающих сопровождать автокомплит IDE от момента запроса до использования результирующих объектов.

По умолчанию сканируется только главный модуль main. Сканирование произвольных модулей можно задать явно:

// аннотирование сущностей произвольного модуля:

$ php bitrix.php orm:annotate -m tasks
// аннотирование нескольких модулей:

$ php bitrix.php orm:annotate -m main,intranet,faceid
// аннотирование всех модулей:

$ php bitrix.php orm:annotate -m all

В ближайшее время мы планируем ввести мониторинг всех известных сущностей в режиме разработки, чтобы при изменении полей перестраивать их аннотации автоматически. Тогда не придется часто использовать консоль.

Частично удобство есть уже в том, что при перегенерации классы заменяются точечно. Если в аннотациях уже есть описанные модули, то при повторном аннотировании одного из них обновится описание только его классов, и другие не будут удалены. Для сброса используйте параметр -c:

$ php bitrix.php orm:annotate -c -m all

Чтобы посмотреть все доступные параметры команды, выполните команду:

$ php bitrix.php help orm:annotate


15
Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
Развернуть комментарии