Модули битрикс - единственный правильный способ добавить в проект на 1С-Битрикс собственную логику так, чтобы она не слетела при следующем обновлении ядра. За годы работы с разными CMS я не раз видел, как разработчик пихает кастомный код прямо в шаблон компонента или в init.php, а потом обновление затирает половину правок. Модуль решает эту проблему: у него своя папка, свои файлы установки и четкие правила, где какому коду место. Разберу, как устроена система модулей, что лежит внутри типового модуля, как подключить готовый и как собрать свой с нуля.
Модульная архитектура 1С-Битрикс: зачем она вообще нужна
Ядро Битрикса с самого начала спроектировано как набор независимых блоков: main отвечает за системные функции, iblock за инфоблоки, catalog за товары, sale за заказы и корзину, form за формы обратной связи. Каждый блок подключается отдельно через CModule::IncludeModule('имя_модуля'), и если модуль не подключен, его классы и функции просто недоступны. Это удобно с точки зрения производительности: сайт не тащит в память код каталога, если на странице нужна только форма.
Для разработчика это же правило работает и с собственным кодом. Если логика интеграции с CRM, эквайрингом или службой доставки оформлена как модуль, ее можно включать и отключать, версионировать и переносить между проектами без переписывания. Я собирал так интеграции с СДЭК для расчета доставки и с Т‑Банк для приема платежей: один раз оформил как модуль, а дальше просто копировал папку в новый проект и подключал через админку.
Структура модуля: обязательные файлы и папки
У любого модуля, системного или кастомного, одинаковый скелет. Разница только в том, что живет внутри.
| Папка или файл | Назначение |
|---|---|
install/index.php |
Класс модуля с методами DoInstall и DoUninstall |
install/version.php |
Номер версии и дата, используется маркетплейсом и админкой |
install/db/ |
SQL-скрипты создания и удаления таблиц |
lib/ |
PHP-классы модуля в стиле D7, автозагрузка по неймспейсу |
admin/ |
Страницы модуля в панели управления |
lang/ru/ |
Языковые файлы, без них админка модуля падает с ошибками |
options.php |
Страница настроек модуля |
include.php |
Подключается автоматически при вызове IncludeModule |
Идентификатор модуля пишется в обратной доменной нотации, например kalinkindev.custommodule, это стандарт Битрикса и он же защищает от конфликтов имен с чужими модулями из маркетплейса.
Как подключить готовый модуль в 1С-Битрикс
Есть два рабочих пути.
Через маркетплейс: раздел «Настройки» -> «Marketplace» -> «Установленные решения», там же поиск и установка платных и бесплатных модулей одним кликом. Подходит для типовых задач вроде интеграции с 1С или популярных платежных систем, когда чужой модуль уже покрывает нужный функционал.
Вручную, если модуль кастомный или найден не в маркетплейсе: папка модуля копируется в /local/modules/ (не в /bitrix/modules/, эта директория перезаписывается при обновлении ядра), после чего в «Настройки» -> «Модули» -> «Из локального репозитория» он появляется в списке и устанавливается кнопкой «Установить». На этом шаге вызывается DoInstall из install/index.php, который создает таблицы в БД, регистрирует обработчики событий и копирует компоненты в публичную часть, если они есть.
При установке вручную первое время часто ловишь ошибку «модуль не найден»: почти всегда причина в неверном регистре имени папки или в отсутствии version.php.
Бесплатный материал
🎁 Полезный скрипт в подарок
Подпишитесь на Telegram - пришлю готовый скрипт по этой теме.
Без спама. Отписка в 1 клик.
Как написать свой модуль с нуля
Проще всего показать на минимальном рабочем каркасе.
1. Создаю папку /local/modules/kalinkindev.custommodule/.
2. Пишу install/version.php с номером версии.
3. Пишу install/index.php с классом, который наследует CModule и реализует DoInstall и DoUninstall.
class kalinkindev_custommodule extends CModule
{
var $MODULE_ID = 'kalinkindev.custommodule';
function DoInstall()
{
RegisterModule($this->MODULE_ID);
RegisterModuleDependences(
'main', 'OnBeforeProlog',
$this->MODULE_ID, 'MyEventHandler', 'CheckSomething'
);
}
function DoUninstall()
{
UnRegisterModuleDependences(
'main', 'OnBeforeProlog',
$this->MODULE_ID, 'MyEventHandler', 'CheckSomething'
);
UnRegisterModule($this->MODULE_ID);
}
}4. В lib/ раскладываю классы по неймспейсу Bitrix\Kalinkindev\Custommodule, автозагрузка подтягивает их без ручных include.
5. Иду в админку и устанавливаю модуль из локального репозитория, как описано выше.
Если модуль должен выполнять фоновые задачи, например раз в час опрашивать статус заказа у СДЭК или синхронизировать остатки, для этого регистрируется агент через CAgent::AddAgent прямо в DoInstall, а не отдельным cron-скриптом мимо ядра, иначе логика потеряется при переносе на другой сервер.
Модули, компоненты и агенты: где что использовать
Путаница между этими тремя понятиями встречается постоянно, особенно у тех, кто пришел в Битрикс после WordPress или Tilda.
| Сущность | Что делает | Когда использовать |
|---|---|---|
| Модуль | Пакет логики, классов и таблиц БД | Своя бизнес-логика, интеграция с внешним API, переиспользуемый код |
| Компонент | Единица вывода на странице (список, форма, каталог) | Отображение данных для пользователя, обычно живет внутри модуля |
| Агент | Функция, вызываемая ядром по расписанию | Фоновые задачи: синхронизация, рассылки, чистка данных |
На практике кастомный модуль почти всегда включает и то, и другое: свои классы в lib/, один-два компонента для вывода на сайте и агент для фоновой синхронизации.
Типичные ошибки при разработке и подключении модулей
За последние проекты на Битриксе чаще всего натыкался на одни и те же грабли.
- Модуль лежит в /bitrix/modules/ вместо /local/modules/, и очередное обновление тихо стирает кастомную логику.
- DoUninstall не удаляет таблицы модуля, из-за чего при переустановке падают SQL-запросы на CREATE TABLE.
- Пути к файлам модуля прописаны абсолютно, а не через GetModuleDir, из-за этого модуль ломается при переносе на другой домен.
- Отсутствуют языковые файлы в lang/ru/, и админка модуля падает белым экраном сразу после установки.
- Смешивание старого процедурного API и нового D7-стиля в одном модуле, что усложняет поддержку и тестирование.
Если задача сложнее одного модуля, например нужна связка модуль плюс внешняя интеграция с CRM или эквайрингом, я обычно советую заранее закладывать время на разработку кастомных модулей под конкретную интеграцию, а не пытаться дописывать логику поверх чужого решения из маркетплейса, это почти всегда выходит дороже в долгосрочной поддержке.
Чтобы сайт работал без сбоев
Техподдержка
от 15 000 ₽/мес
Подробнее →Частые вопросы
Чем модуль отличается от компонента в Битрикс?
Модуль это пакет с классами, таблицами БД и своей установкой, а компонент - единица вывода данных на странице сайта. Компонент почти всегда работает внутри какого-то модуля и использует его классы, но сам по себе таблиц не создает и событий не регистрирует.
Можно ли редактировать чужой модуль из маркетплейса?
Технически файлы доступны для правки, но при обновлении модуля через маркетплейс любые изменения будут затерты. Если нужна кастомизация чужого решения, правильный подход - обернуть его своим модулем с обработчиками событий, а не лезть в исходники напрямую.
Где хранить кастомные модули, чтобы их не затерло обновление?
Только в /local/modules/, это официально поддерживаемая директория для собственного кода, ее не трогают ни обновления ядра, ни обновления системных модулей из /bitrix/modules/.
Сколько стоит разработка кастомного модуля под 1С-Битрикс?
Зависит от объема: простая обертка над одним внешним API это несколько дней работы, а модуль с админкой, агентами и несколькими интеграциями может растянуться на пару недель. Оценку конкретной задачи обычно даю на консультации от 3 000 ₽, а после сдачи проекта можно взять техподдержку модуля от 15 000 ₽ в месяц, чтобы не разбираться самому при следующем обновлении ядра.