Создание своего модуля в Битрикс: Структура, install/index.php и version.php

Модуль — это основной способ расширения функциональности Битрикс.

Создание собственного модуля позволяет инкапсулировать бизнес-логику, компоненты, классы и административные страницы в единый, легко устанавливаемый пакет.

Шаг 1: Структура папок

Все кастомные модули должны располагаться в /local/modules/.

Название папки модуля должно соответствовать формату partner_code.module_name (например, mycompany.custommodule).

Минимальная обязательная структура:

/local/modules/mycompany.custommodule/
|-- include.php             # Файл, подключаемый при загрузке модуля
|-- install/
|   |-- index.php           # Главный файл-инсталлятор
|   `-- version.php         # Файл с версией модуля
`-- lang/
    `-- ru/
        `-- install/
            `-- index.php   # Языковой файл для инсталлятора

Шаг 2: Файл версии (install/version.php)

Этот файл содержит массив $arModuleVersion с информацией о текущей версии модуля.

Он необходим для системы обновлений.

// /local/modules/mycompany.custommodule/install/version.php
<?
$arModuleVersion = array(
    "VERSION" => "1.0.0",
    "VERSION_DATE" => "2024-10-26 12:00:00"
);
?>

Шаг 3: Языковой файл инсталлятора (lang/ru/install/index.php)

Здесь хранятся все текстовые строки для инсталлятора.

// /local/modules/mycompany.custommodule/lang/ru/install/index.php
<?
$MESS["MYMODULE_MODULE_NAME"] = "Мой кастомный модуль";
$MESS["MYMODULE_MODULE_DESC"] = "Описание моего кастомного модуля.";
$MESS["MYMODULE_PARTNER_NAME"] = "Моя компания";
$MESS["MYMODULE_PARTNER_URI"] = "https://mycompany.com";

Шаг 4: Главный файл-инсталлятор (install/index.php)

Это класс, который управляет установкой и удалением модуля. Название класса должно совпадать с названием папки модуля, с заменой точек на подчеркивания. Для mycompany.custommodule класс будет mycompany_custommodule.

// /local/modules/mycompany.custommodule/install/index.php
<?
use Bitrix\Main\Localization\Loc;
use Bitrix\Main\ModuleManager;

Loc::loadMessages(__FILE__);

class mycompany_custommodule extends CModule
{
    var $MODULE_ID = "mycompany.custommodule";
    var $MODULE_VERSION;
    var $MODULE_VERSION_DATE;
    var $MODULE_NAME;
    var $MODULE_DESCRIPTION;
    var $PARTNER_NAME;
    var $PARTNER_URI;

    function __construct()
    {
        $arModuleVersion = [];
        include(__DIR__ . "/version.php");

        $this->MODULE_VERSION = $arModuleVersion["VERSION"];
        $this->MODULE_VERSION_DATE = $arModuleVersion["VERSION_DATE"];
        
        $this->MODULE_NAME = Loc::getMessage("MYMODULE_MODULE_NAME");
        $this->MODULE_DESCRIPTION = Loc::getMessage("MYMODULE_MODULE_DESC");
        $this->PARTNER_NAME = Loc::getMessage("MYMODULE_PARTNER_NAME");
        $this->PARTNER_URI = Loc::getMessage("MYMODULE_PARTNER_URI");
    }

    // Метод установки
    function DoInstall()
    {
        // Регистрируем модуль в системе
        ModuleManager::registerModule($this->MODULE_ID);
        
        // Здесь можно добавить логику создания таблиц, копирования файлов,
        // регистрации событий и т.д.
        
        return true;
    }

    // Метод удаления
    function DoUninstall()
    {
        // Здесь логика удаления таблиц, файлов, событий...

        // Дерегистрируем модуль
        ModuleManager::unRegisterModule($this->MODULE_ID);
        
        return true;
    }
}

Разбор класса: Свойства: $MODULE_ID, $MODULE_NAME и др. заполняются в конструкторе из version.php и языковых файлов.

$MODULE_ID должен строго совпадать с названием папки. __construct(): Конструктор, который инициализирует все свойства.

DoInstall(): Выполняется при установке модуля.

Минимальное действие — ModuleManager::registerModule().

Здесь вы можете создавать таблицы БД, копировать файлы (например, компоненты или страницы в /bitrix/admin/), регистрировать обработчики событий (RegisterModuleDependences).

DoUninstall():

Выполняется при удалении. Должен выполнять обратные действия: удалять таблицы, файлы, отменять регистрацию событий (`UnRegisterModuleDependences`).

Шаг 5: Файл include.php

Это пустой файл, который будет автоматически подключен Битриксом при каждом хите, если модуль установлен и активен.

В дальнейшем в него можно будет добавить, например, автозагрузку классов.

// /local/modules/mycompany.custommodule/include.php
<?
// Тут можно будет регистрировать классы для автозагрузки
?>

Готово!
Теперь, если вы зайдете в /bitrix/admin/partner_modules.php, вы увидите свой модуль в списке и сможете его установить.

Пример еще структуры модуля my.module:

/local/modules/my.module/
├── install/                // Файлы установки [19, 20]
│   ├── components/         // Размещение компонентов, например, my/user.card/ [19, 20]
│   └── index.php           // Файл установки модуля [19, 20]
├── lib/                    // Папка для основных классов, сервисов и контроллеров [19, 21]
│   ├── controller/         // Папка для контроллеров [19, 20]
│   │   └── user.php
│   └── Services/           // Папка для сервисов, например, LikeService.php [19, 21]
└── .settings.php           // Файл с конфигурацией модуля [21]

Папка /lib/ предназначена для основных классов. Если классы регистрируются для автозагрузки, они размещаются в папке /lib/.

Конфигурация модуля (.settings.php) Для корректной работы компонентов модуля (например, контроллеров), необходимо зарегистрировать его конфигурацию в файле .settings.php в корне модуля. Например, для регистрации контроллера необходимо указать пространство имен по умолчанию:

return [
    'controllers' => [
        'value' => [
            'defaultNamespace' => '\\My\\Module\\Controller', // Пространство имен контроллеров [23, 24]
        ],
        'readonly' => true,
    ]
];

Это позволяет системе находить контроллеры по сокращенному имени действия.

Регистрация классов и автозагрузка Для упрощения работы с классами используется автозагрузка (autoloading). В файле /local/modules/[ваш_модуль]/include.php можно регистрировать часто используемые классы или пространства имен по стандарту PSR-4. Если классы для узких задач не регистрируются, они загрузятся автоматически при первом обращении.

Взаимодействие с ядром через Service Locator Модули могут предоставлять свои сервисы, которые регистрируются через механизм Service Locator. Регистрация сервисов модуля осуществляется в файле {moduleName}/.settings.php. Рекомендуется использовать префикс имени модуля для обеспечения уникальности сервисов, например: disk.urlManager

Вывод:
Создание модуля — это первый шаг к написанию профессионального и переносимого кода на Битрикс.

Правильная структура и грамотно написанный инсталлятор позволяют легко распространять ваш функционал и управлять им, отделяя его от ядра системы и других доработок.

создать модуль Битрикс, структура модуля, install/index.php, DoInstall, DoUninstall, version.php, кастомный модуль.