Создание собственного модуля в Битрикс

Создание собственного модуля — способ оформить бизнес-логику проекта так, чтобы она не зависела от конкретного шаблона сайта и переживала его смену. Разберём минимальную структуру модуля, обязательные файлы установки и типичные ошибки при первом самостоятельном модуле.

Минимальная структура каталога

/local/modules/vendor.module/
├── include.php
├── install/
│   ├── index.php
│   └── db/
│       └── install.php
└── lib/
    └── TaskTable.php

Имя модуля традиционно состоит из префикса вендора и названия через точку (vendor.module) — это не просто соглашение, а способ избежать конфликта имён с другими модулями, включая сторонние решения из Маркетплейса.

Файл install/index.php

<?php

use Bitrix\Main\ModuleManager;
use Bitrix\Main\Loader;

class vendor_module extends CModule
{
    public $MODULE_ID = 'vendor.module';
    public $MODULE_NAME = 'Мой модуль';
    public $MODULE_DESCRIPTION = 'Описание модуля';
    public $MODULE_VERSION = '1.0.0';
    public $MODULE_VERSION_DATE;

    public function __construct()
    {
        $this->MODULE_VERSION_DATE = '2026-01-01 00:00:00';
    }

    public function DoInstall()
    {
        ModuleManager::registerModule($this->MODULE_ID);
        $this->InstallDB();
    }

    public function DoUninstall()
    {
        $this->UnInstallDB();
        ModuleManager::unRegisterModule($this->MODULE_ID);
    }

    public function InstallDB()
    {
        global $DB;
        $DB->RunSQLBatch(__DIR__ . '/db/install.sql');
    }

    public function UnInstallDB()
    {
        global $DB;
        $DB->Query('DROP TABLE IF EXISTS vendor_module_task');
    }
}

Этот класс — точка входа установки модуля, которую видит система при заходе в раздел Настройки → Настройки продукта → Модули. Без него модуль технически лежит в каталоге, но не появится в списке доступных для установки.

Файл include.php

<?php

use Bitrix\Main\Loader;

Loader::registerAutoLoadClasses('vendor.module', [
    '\Vendor\Module\TaskTable' => 'lib/TaskTable.php',
]);

include.php подключается автоматически при вызове Loader::includeModule('vendor.module') — здесь регистрируется автозагрузка классов модуля, чтобы не писать require вручную на каждый файл.

Подключение модуля в коде

<?php

use Bitrix\Main\Loader;

if (Loader::includeModule('vendor.module')) {
    $tasks = \Vendor\Module\TaskTable::getList([]);
}

Регистрация обработчиков событий из своего модуля

<?php

use Bitrix\Main\EventManager;

$eventManager = EventManager::getInstance();
$eventManager->addEventHandler(
    'sale',
    'OnSaleOrderSaved',
    ['\Vendor\Module\OrderHandler', 'onOrderSaved']
);

Этот код обычно размещают в обработчике OnAfterEpilog главного модуля или подключают через файл init.php проекта — сам класс CModule модуля не является местом для регистрации runtime-обработчиков, только для действий установки и удаления.

Права доступа к папке модулей

Каталог /local/modules/ предпочтителен для собственных модулей перед /bitrix/modules/ — последний относится к системным и сторонним модулям, устанавливаемым из Маркетплейса, и его содержимое может быть переписано при обновлении системных компонентов.

Частые ошибки

• Имя модуля без префикса вендора. Риск конфликта с другим модулем, использующим то же короткое имя.
• Модуль размещён в /bitrix/modules/ вместо /local/modules/. Риск потери кастомного модуля при обновлении системных компонентов.
• Регистрация обработчиков событий внутри install/index.php. Обработчики не сработают в runtime — это файл только для установки и удаления.
• DoUninstall не удаляет собственные таблицы. После удаления модуля в базе остаются мёртвые таблицы.

Итог

Собственный модуль — это каталог с обязательным классом установки в install/index.php, файлом автозагрузки include.php и произвольной структурой lib/ для кода. Размещение в /local/modules/ с уникальным префиксом вендора в имени защищает модуль от конфликтов и потери при системных обновлениях.