Разработка по стандартам Битрикс

c

Разработка на «1С-Битрикс» без следования официальным стандартам превращает проект в нагромождение устаревшего кода, конфликтующих модулей и нестабильной архитектуры. Ниже — технический чек-лист, построенный на актуальных требованиях Bitrix Framework (версии с D7-ядром, PHP 8.x, 2026). Каждый пункт содержит конкретные параметры, примеры кода и критерии проверки. Используйте этот список как основу код-ревью, нагрузочного тестирования и приёмки модулей.

1. Обязательная структура модуля и пространства имён

Любой пользовательский модуль должен быть зарегистрирован через файл install/index.php с корректным vendor-префиксом (например, company.modulename). Все классы обязаны лежать в папке lib/ и иметь неймспейсы вида Bitrix\Company\Modulename\. Запрещено использование глобальных функций без пространства имён — только статические методы классов с аннотацией @throws \Bitrix\Main\SystemException для обработки ошибок.

Проверка: при запуске bitrix:module.admin.list модуль должен отображаться с версией, и не должно быть ошибок автозагрузки. Все файлы в lib/ должны иметь строгую типизацию (declare(strict_types=1)) и корректный хедер с лицензией.

  1. Регистрация через D7-методы: используйте \Bitrix\Main\ModuleManager::registerModule() в install/index.php, а не ручные SQL-скрипты.
  2. PSR-4-автозагрузка: в composer.json пропишите "autoload": { "psr-4": { "Bitrix\\Company\\Modulename\\": "lib/" } } — это гарантирует работу автотестов и совместимость с PHPStan.
  3. Строгая типизация: все методы классов должны содержать тип параметров и возвращаемого значения (int, string, array, ?bool). Исключение — только для обратной совместимости с легаси-модулями.
  4. Миграции базы данных: в папке install/db/mysql/ должны быть install.sql и, опционально, uninstall.sql. Используйте \Bitrix\Main\Entity\Base::getEntity()->compileDbTableStructureDump() для генерации.
  5. Отсутствие global $DB: все запросы к БД — только через ORM-сущности или \Bitrix\Main\Application::getConnection(). Пример: \Bitrix\Main\Entity\Query::getInstance().
  6. Единый файл событий: в install/step.php используйте RegisterModuleDependences() только для ядра; для своих модулей — \Bitrix\Main\EventManager::getInstance()->registerEventHandler().
  7. Проверка лицензионной чистоты: в каждом файле должен быть блок комментариев с copyright и указанием версии модуля — это проверяется аудитом партнёров.

2. ORM-сущности и DataManager: правила создания и использования

Каждая ORM-сущность должна наследовать \Bitrix\Main\ORM\Data\DataManager и определять метод getMap(), возвращающий массив с полями типа \Bitrix\Main\ORM\Fields\IntegerField, StringField и т.д. Запрещается создавать поля без nullable-флага (nullable => true), если это не primary key. Все связи (reference) должны быть строго типизированы через ReferenceField с указанием join_type (LEFT/INNER).

Практический пример: вместо Entity::getList с массивом сортировки используйте Query::getInstance() с fluent-интерфейсом. Это даёт возможность дебага через query->getQuery() и повышает читаемость.

  1. Поля с версионированием: для таблиц, где возможны изменения, обязательно добавьте поле UF_VERSION типа IntegerField и инкрементируйте его в BeforeUpdate-обработчике.
  2. Индексы через ORM: в getMap() добавляйте 'index' => true для полей, участвующих в filter.
  3. Отсутствие прямых SQL-запросов: если требуется сложный JOIN, используйте \Bitrix\Main\ORM\Query\Query с registerRuntimeField(), а не $DB->Query().
  4. Кэширование запросов: для часто запрашиваемых сущностей (например, справочники) применяйте \Bitrix\Main\Data\Cache::createInstance() с TTL не менее 3600 секунд.
  5. Валидация данных: в классах полей переопределите метод validate(), выбрасывая \Bitrix\Main\ArgumentException при несоответствии формату.
  6. Права доступа на уровне сущности: если данные должны быть изолированы по группам пользователей, используйте \Bitrix\Main\ORM\Fields\Relations\Reference на таблицу b_user_group.
  7. Автоматические тесты: для каждой ORM-сущности напишите PHPUnit-тест, проверяющий корректную вставку, обновление и удаление записи. Используйте транзакционный откат после каждого теста.

3. Агенты, события и почтовые шаблоны: стандарты реализации

Агенты должны быть оформлены как статические методы классов с возвратом string следующего вызова. Используйте \Bitrix\Main\Agent::addAgent() только на этапе установки модуля, не через HP. Для регулярных агентов обязательно задавайте интервал (interval), а не время старта. Убедитесь, что функция агента не зависит от global переменных, иначе при параллельной обработке будут конфликты.

События (event handlers) должны регистрироваться в install/step.php через registerEventHandler с указанием sender и module_id. Запрещается подвешивать событие прямо в коде компонента — это приводит к трудно отлаживаемым циклическим вызовам.

  1. Агенты с гранулярностью: для задач, выполняющихся раз в час, используйте interval: 3600, а не next_exec: date() + 3600.
  2. Логирование в агентах: каждый агент должен писать в \Bitrix\Main\Diag\Debug::writeToFile() начало и конец выполнения — это помогает при сбоях.
  3. Почтовые шаблоны: все письма формируются через \Bitrix\Main\Mail\Event::send() с явным указанием FIELDS и EVENT_NAME. Шаблоны должны храниться в файлах /local/templates/.default/components/bitrix/main.mail.template/.
  4. Проверка на дубли: перед добавлением агента через addAgent() всегда вызывайте \Bitrix\Main\Agent::getList() с фильтром по имени — иначе при повторной установке модуля возникнут копии.
  5. Обработка исключений: в теле агента обязателен try-catch, логирующий ошибку в CEventLog::Log. Без этого агент при первом же исключении «зависает».
  6. События без зависимостей: в обработчике события не вызывайте другие события того же модуля, чтобы избежать бесконечной рекурсии.
  7. Производительность: агенты, работающие с большими наборами данных (более 1000 записей), обязаны использовать постраничную обработку (\Bitrix\Main\ORM\Query\Query::setLimit(100)).

4. Компоненты и шаблоны: требования к namespace и безопасности

Все компоненты должны быть зарегистрированы через \CBitrixComponent с переопределением метода executeComponent(). Шаблоны компонентов не должны содержать логику — только вызов $arResult и HTML-разметку. Для защиты от XSS все данные, выводимые в шаблоне, проходят через htmlspecialcharsbx(). Кастомные компоненты размещайте в /local/components/vendor/componentname/.

Архитектурное требование: компонент не должен напрямую обращаться к $_REQUEST — все входящие параметры принимаются через $arParams и валидируются в методе onPrepareComponentParams(). Используйте \Bitrix\Main\HttpRequest::getInstance() только в случае крайней необходимости.

  1. Защита от CSRF: в форму компонента обязательно добавляйте bitrix_sessid_post() и проверяйте сессию через check_bitrix_sessid().
  2. Кэширование компонента: используйте $this->arParams['CACHE_TYPE'] и $this->arParams['CACHE_TIME']. Для сложных выборок — \Bitrix\Main\Data\Cache::initCache().
  3. Шаблоны с наследованием: если один компонент использует шаблон другого, наследуйте через parent::executeComponent(), не копируя код.
  4. Отсутствие SQL в шаблонах: любой запрос к БД — только в классе компонента. Шаблон получает уже готовые массивы.
  5. Локализация: все строки в шаблоне должны быть вынесены в .lang.php файлы. Не используйте прямые русские строки.
  6. Проверка прав доступа: в методе executeComponent() вызывайте $this->includeComponentTemplate() после проверки \Bitrix\Main\Engine\CurrentUser::get()->isAdmin() или прав по модулю.
  7. Автотесты для компонентов: напишите функциональные тесты, которые отправляют POST-запрос на компонент и проверяют корректность $arResult.

5. Производительность, безопасность и рефакторинг устаревшего кода

Перед сдачей проекта обязателен аудит производительности через встроенный \Bitrix\Main\Diag\Debug::startTimeLabel(). Все запросы к БД не должны превышать 200 мс. Устаревшие методы (CModule::IncludeModule(), GetMessage() без параметров, CGI::setCookie()) подлежат замене на D7-аналоги. Для PHP 8.x следите за строгими типами и отказом от deprecated-функций (например, create_function() полностью запрещена).

Безопасность: все пользовательские данные, приходящие из $arParams или $_FILES, фильтруются через \Bitrix\Main\Web\Uri::toArray() и \Bitrix\Main\Text\Encoding::convertEncoding(). Запрещено использование eval() в любом коде, включая шаблоны.

  1. Мониторинг запросов: включите Debug::dump() только на dev-окружении; на production обязательно отключайте через Debug::disable().
  2. Кэширование конфигурации: используйте \Bitrix\Main\Config\Configuration::getInstance() с кэшем в APCu.
  3. Замена старых методов: вместо CUser::GetList() — \Bitrix\Main\UserTable::getList(); вместо CIBlockElement::GetList() — ORM-сущности инфоблоков;
  4. Проверка на инъекции: все SQL-запросы в агентах и событиях должны использовать prepared statements (\Bitrix\Main\DB\SqlQuery::prepare()).
  5. Удаление неиспользуемого кода: перед релизом удалите require_once на несуществующие файлы — это ускоряет автозагрузку.
  6. PHPStan уровень 6: настройте статический анализ на strict-режиме, ошибки исправляйте до выкладки.
  7. Документация по нестандартным решениям: если отступаете от стандарта (например, используете global $USER для совместимости), обязательно добавьте комментарий с объяснением и планом миграции.

Этот чек-лист охватывает только те аспекты, которые специфичны для «1С-Битрикс» и отличаются от разработки на чистом PHP или других CMS. Соблюдение этих пунктов гарантирует совместимость с обновлениями ядра, лёгкую поддержку и прохождение аудита партнёров. Используйте его как основу для код-ревью и технического задания на модули.

Добавлено: 23.04.2026