Аннотации классов
Большая часть методов Объекта и Коллекции - виртуальные, обрабатываются через magic вызов __call. В то же время они сделаны для интуитивно понятных и говорящих именованных методов, и без автокомплита в IDE их ценность резко снижается.
Чтобы IDE все же знала об их существовании и помогала ориентироваться в большом количестве классов и методов, мы сделали для нее специальный служебный файл с аннотациями всех сущностей.
С версии 20.100.0 Главного модуля (main) файл с аннотациями ORM-классов ядра включен в поставку и расположен в /bitrix/modules/main/meta/orm.php.
Для генерации таких аннотаций используется cli-команда orm:annotate:
Примечание: перед использованием CLI-окружения убедитесь, что установили зависимости проекта через composer.
В процессе выполнения команды производится сканирование модулей, а именно всех файлов из папок bitrix/modules/[module]/lib. Если в файле обнаруживается "маппинг" сущности (класс Table, подкласс Bitrix\Main\ORM\Data\DataManager), то анализируется ее карта (список полей).
Результатом команды является файл (по умолчанию bitrix/modules/orm_annotations.php), который содержит описания классов Объекта и Коллекции сущностей. Также в нем декларируются дубликат класса Table и несколько фактически несуществующих вспомогательных классов, помогающих сопровождать автокомплит IDE от момента запроса до использования результирующих объектов.
По умолчанию сканируется только главный модуль main. Сканирование произвольных модулей можно задать явно:
В ближайшее время мы планируем ввести мониторинг всех известных сущностей в режиме разработки, чтобы при изменении полей перестраивать их аннотации автоматически. Тогда не придется часто использовать консоль.
Частично удобство есть уже в том, что при перегенерации классы заменяются точечно. Если в аннотациях уже есть описанные модули, то при повторном аннотировании одного из них обновится описание только его классов, и другие не будут удалены. Для сброса используйте параметр -c:
Чтобы посмотреть все доступные параметры команды, выполните команду: