Команды ORM

Стандартная команда Битрикс для работы с ORM: сканирование и генерация аннотаций.

`orm:annotate`

Сканирует проект на наличие ORM-сущностей и генерирует аннотации для улучшения автодополнения в IDE.

Синтаксис

bash

php bitrix.php orm:annotate [output] [опции]

Аргументы

output - путь к файлу для сохранения аннотаций (необязательный, по умолчанию: bitrix/modules/orm_annotations.php)

Опции

--modules=<список> или -m - модули для сканирования через запятую (по умолчанию: main)
--clean или -c - очистить текущую карту сущностей перед генерацией

Примеры использования

bash

# Генерация аннотаций (по умолчанию в bitrix/modules/orm_annotations.php)
php bitrix.php orm:annotate

# С указанием файла для сохранения
php bitrix.php orm:annotate /path/to/orm_annotations.php

# Сканирование конкретных модулей
php bitrix.php orm:annotate --modules=main,iblock,catalog

# Сканирование всех модулей
php bitrix.php orm:annotate --modules=all

# Очистка существующей карты и создание новой
php bitrix.php orm:annotate --clean

# Комбинированный пример
php bitrix.php orm:annotate \
  /local/php_interface/orm_annotations.php \
  --modules=main,iblock,catalog,sale \
  --clean

Что делает команда

Команда выполняет следующие действия:

Сканирует модули - находит все классы, наследующие DataManager
Анализирует структуру - определяет поля, связи и методы
Генерирует аннотации - создает PHPDoc аннотации для IDE
Создает файл метаданных - сохраняет карту сущностей

Результат

Создается файл с PHPDoc аннотациями, который помогает IDE:

Распознавать ORM-сущности
Предоставлять автодополнение для полей и методов
Улучшать навигацию по коду
Показывать подсказки по типам

Пример сгенерированного файла

php

<?php
/**
 * @method static EO_User_Query query()
 * @method static EO_User_Result getByPrimary($primary)
 * @method static EO_User_Result getById($id)
 * @method static EO_User_Result getList(array $parameters = [])
 * @method static EO_User_Entity getEntity()
 */
class Bitrix\Main\UserTable
{
}

/**
 * @property int $ID
 * @property string $LOGIN
 * @property string $EMAIL
 * @property string $NAME
 * @property string $LAST_NAME
 */
class EO_User
{
}

Использование

Базовая генерация после установки модулей

bash

#!/bin/bash
# Генерация аннотаций после установки нового модуля

MODULE_ID="$1"

cd /var/www/bitrix

# Установить модуль
php bitrix.php module:install "$MODULE_ID"

# Регенерировать аннотации для всех модулей
php bitrix.php orm:annotate --modules=all --clean

echo "Модуль $MODULE_ID установлен, аннотации обновлены"

Регулярное обновление аннотаций

bash

#!/bin/bash
# Еженедельное обновление ORM-аннотаций

cd /var/www/bitrix

echo "Обновление ORM-аннотаций: $(date)"

# Генерация для основных модулей
php bitrix.php orm:annotate \
  --modules=main,iblock,catalog,sale,crm \
  --clean \
  -v

echo "Аннотации обновлены"

Генерация для кастомных модулей

bash

#!/bin/bash
# Генерация аннотаций только для кастомных модулей компании

cd /var/www/bitrix

# Найти все кастомные модули
CUSTOM_MODULES=$(ls -d /local/modules/company.* 2>/dev/null | xargs -n1 basename | tr '\n' ',')

if [ -n "$CUSTOM_MODULES" ]; then
    # Удалить последнюю запятую
    CUSTOM_MODULES=${CUSTOM_MODULES%,}
    
    echo "Генерация аннотаций для модулей: $CUSTOM_MODULES"
    
    php bitrix.php orm:annotate \
      /local/php_interface/orm_custom_annotations.php \
      --modules="$CUSTOM_MODULES" \
      --clean
    
    echo "Аннотации для кастомных модулей созданы"
else
    echo "Кастомные модули не найдены"
fi

Интеграция в CI/CD

bash

#!/bin/bash
# Автоматическая генерация аннотаций при деплое

cd /var/www/bitrix

# Обновить код
git pull origin master

# Установить зависимости
composer install

# Обновить модули
php bitrix.php update:modules

# Регенерировать аннотации
php bitrix.php orm:annotate --modules=all --clean

# Закоммитить обновленные аннотации (опционально)
if [ -f "modules/orm_annotations.php" ]; then
    git add modules/orm_annotations.php
    git commit -m "chore: обновлены ORM-аннотации" || true
fi

echo "Деплой завершен, аннотации обновлены"

Продвинутые сценарии

Раздельная генерация для разных окружений

bash

#!/bin/bash
# Разные аннотации для development и production

cd /var/www/bitrix

ENV="${1:-development}"

case $ENV in
    development)
        # Для разработки - все модули
        php bitrix.php orm:annotate \
          /local/php_interface/orm_annotations_dev.php \
          --modules=all \
          --clean
        ;;
    production)
        # Для продакшена - только необходимые
        php bitrix.php orm:annotate \
          modules/orm_annotations.php \
          --modules=main,iblock,catalog,sale \
          --clean
        ;;
    *)
        echo "Неизвестное окружение: $ENV"
        exit 1
        ;;
esac

echo "Аннотации для окружения $ENV сгенерированы"

Мониторинг изменений ORM-структуры

bash

#!/bin/bash
# Отслеживание изменений в ORM-структуре

cd /var/www/bitrix

CURRENT="/tmp/orm_current.php"
PREVIOUS="/var/cache/orm_previous.php"

# Сгенерировать текущие аннотации
php bitrix.php orm:annotate "$CURRENT" --modules=all

# Сравнить с предыдущей версией
if [ -f "$PREVIOUS" ]; then
    if ! diff -q "$PREVIOUS" "$CURRENT" > /dev/null; then
        {
            echo "Обнаружены изменения в ORM-структуре:"
            echo "Дата: $(date)"
            echo ""
            diff -u "$PREVIOUS" "$CURRENT"
        } | mail -s "ORM Structure Changed" admin@example.com
    fi
fi

# Сохранить текущую версию
cp "$CURRENT" "$PREVIOUS"

Генерация документации по ORM-сущностям

bash

#!/bin/bash
# Создание документации на основе ORM-аннотаций

cd /var/www/bitrix

ANNOTATIONS="/tmp/orm_annotations.php"
DOCS="/docs/orm_entities.md"

# Сгенерировать аннотации
php bitrix.php orm:annotate "$ANNOTATIONS" --modules=all --clean

# Извлечь информацию о сущностях
{
    echo "# ORM-сущности проекта"
    echo ""
    echo "Дата генерации: $(date)"
    echo ""
    
    # Извлечь классы DataManager
    grep -A 5 "class.*DataManager" "$ANNOTATIONS" | while read -r line; do
        if [[ $line =~ class.*DataManager ]]; then
            entity=$(echo "$line" | grep -oP '\\K[\w\\]+(?=\s*$)')
            echo "## $entity"
            echo ""
        fi
    done
} > "$DOCS"

echo "Документация создана: $DOCS"

Автоматическое обновление после миграций

bash

#!/bin/bash
# Обновление аннотаций после выполнения миграций

cd /var/www/bitrix

# Выполнить миграции (например, sprint.migration)
php bitrix.php sprint:migrate

# Обновить аннотации
php bitrix.php orm:annotate --modules=all --clean

# Очистить кеш ORM
php bitrix.php cache:type:clear orm

echo "Миграции выполнены, аннотации обновлены"

Troubleshooting

Аннотации не генерируются

Проблема: Команда выполняется, но файл не создается

Решения:

Проверьте права доступа к целевой директории
Убедитесь, что модули установлены и активны
Проверьте наличие ORM-классов в модулях
Используйте опцию -v для подробного вывода

IDE не видит аннотации

Проблема: После генерации автодополнение не работает

Решения:

Перезапустите IDE
Invalidate Caches в PhpStorm
Убедитесь, что файл аннотаций находится в индексируемой директории
Проверьте, что файл не игнорируется в .gitignore

Ошибка "Out of memory"

Проблема: Недостаточно памяти при генерации для всех модулей

Решения:

Увеличьте memory_limit в php.ini
Генерируйте аннотации по частям (по модулям)
Используйте инкрементальную генерацию
Оптимизируйте список сканируемых модулей

Устаревшие аннотации

Проблема: Аннотации не соответствуют текущей структуре

Решения:

Используйте опцию --clean для полной перегенерации
Настройте автоматическое обновление после изменений
Регулярно запускайте команду в cron

Полезные советы

💡 Регулярно обновляйте - настройте автоматическое обновление после изменений

💡 Версионируйте - коммитьте файл аннотаций в Git для синхронизации команды

💡 Используйте --clean - при проблемах полностью перегенерируйте аннотации

💡 Оптимизируйте список модулей - не сканируйте лишние модули

💡 Интегрируйте в CI/CD - автоматизируйте генерацию при деплое

💡 Мониторьте изменения - отслеживайте изменения структуры автоматически

💡 Документируйте - используйте аннотации для создания документации

Смотрите также

Команды make - создание ORM-классов для таблиц
Команды разработки - генерация метаданных для IDE
Официальная документация Битрикс по ORM

Команды ORM ​

orm:annotate ​

Синтаксис ​

Аргументы ​

Опции ​

Примеры использования ​

Что делает команда ​

Результат ​

Пример сгенерированного файла ​

Использование ​

Базовая генерация после установки модулей ​

Регулярное обновление аннотаций ​

Генерация для кастомных модулей ​

Интеграция в CI/CD ​

Продвинутые сценарии ​

Раздельная генерация для разных окружений ​

Мониторинг изменений ORM-структуры ​

Генерация документации по ORM-сущностям ​

Автоматическое обновление после миграций ​

Troubleshooting ​

Аннотации не генерируются ​

IDE не видит аннотации ​

Ошибка "Out of memory" ​

Устаревшие аннотации ​

Полезные советы ​

Смотрите также ​

Команды ORM

`orm:annotate`

Синтаксис

Аргументы

Опции

Примеры использования

Что делает команда

Результат

Пример сгенерированного файла

Использование

Базовая генерация после установки модулей

Регулярное обновление аннотаций

Генерация для кастомных модулей

Интеграция в CI/CD

Продвинутые сценарии

Раздельная генерация для разных окружений

Мониторинг изменений ORM-структуры

Генерация документации по ORM-сущностям

Автоматическое обновление после миграций

Troubleshooting

Аннотации не генерируются

IDE не видит аннотации

Ошибка "Out of memory"

Устаревшие аннотации

Полезные советы

Смотрите также