Свой модуль для Битрикс: структура и установка

Модуль в Битрикс — это набор файлов с определённой структурой, которые система умеет устанавливать, регистрировать в базе и подключать автоматически. После установки модуль получает собственное пространство имён, страницу настроек в админке и возможность добавлять обработчики событий.

Что нужно до начала

Убедитесь, что у вас есть:

• Битрикс редакции Старт или выше, версия 20.x и новее — структура модулей одинаковая, но в более старых версиях могут отличаться методы API;
• доступ к файловой системе сервера по FTP или SSH;
• понимание базового PHP — классы, методы, пространства имён;
• права на вход в административную часть сайта.

Проверка: откройте раздел «Настройки → Настройки продукта → Модули» в админке. Если видите список установленных модулей — всё готово для работы.

Шаг 1. Создайте структуру папок модуля

Модули Битрикс хранятся в /local/modules/ (для пользовательских) или /bitrix/modules/ (для системных). Всегда используйте /local/ — при обновлении системы содержимое этой папки не затирается.

Имя модуля состоит из вендора и названия через точку: vendor.modulename. Вендор — ваш идентификатор (имя компании или ник латиницей), название — суть модуля. Пример: mycompany.customapi.

Создайте структуру:

/local/modules/mycompany.customapi/
├── install/
│   ├── index.php
│   └── version.php
├── lang/
│   └── ru/
│       ├── install/
│       │   └── index.php
│       └── options.php
├── lib/
└── options.php

Где:

• install/index.php — класс установщика с методами установки и удаления;
• install/version.php — файл с версией и датой модуля;
• lang/ru/ — языковые файлы для интерфейса;
• lib/ — ваши классы, автозагружаемые через пространство имён;
• options.php — страница настроек модуля в админке.

Проверка: убедитесь, что путь /local/modules/mycompany.customapi/install/index.php существует и доступен для записи.

Шаг 2. Напишите дескриптор версии

Файл install/version.php содержит массив с версией и датой последнего обновления. Битрикс читает его при выводе списка модулей и при проверке обновлений.

<?php
$arModuleVersion = [
    'VERSION' => '1.0.0',
    'VERSION_DATE' => '2024-01-15 12:00:00',
];

Формат даты — YYYY-MM-DD HH:MM:SS. При каждом обновлении модуля увеличивайте версию и меняйте дату.

Проверка: откройте файл в браузере напрямую — вы должны увидеть пустую страницу без ошибок PHP.

Шаг 3. Создайте класс установщика

Файл install/index.php содержит класс, унаследованный от CModule. Этот класс Битрикс вызывает при установке и удалении модуля.

<?php

use Bitrix\Main\Localization\Loc;
use Bitrix\Main\ModuleManager;

Loc::loadMessages(__FILE__);

class mycompany_customapi extends CModule
{
    public function __construct()
    {
        $arModuleVersion = [];
        include __DIR__ . '/version.php';

        $this->MODULE_ID = 'mycompany.customapi';
        $this->MODULE_VERSION = $arModuleVersion['VERSION'];
        $this->MODULE_VERSION_DATE = $arModuleVersion['VERSION_DATE'];
        $this->MODULE_NAME = Loc::getMessage('MYCOMPANY_CUSTOMAPI_MODULE_NAME');
        $this->MODULE_DESCRIPTION = Loc::getMessage('MYCOMPANY_CUSTOMAPI_MODULE_DESC');
        $this->PARTNER_NAME = Loc::getMessage('MYCOMPANY_CUSTOMAPI_PARTNER_NAME');
        $this->PARTNER_URI = 'https://example.com';
    }

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

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

Обратите внимание:

• Имя класса состоит из вендора и названия модуля через подчёркивание: mycompany_customapi;
• MODULE_ID — идентификатор модуля, совпадает с именем папки;
• DoInstall() регистрирует модуль в системе через ModuleManager::registerModule();
• DoUninstall() удаляет запись о модуле из базы.

Проверка: файл должен быть без синтаксических ошибок. Выполните php -l /local/modules/mycompany.customapi/install/index.php — команда должна вернуть «No syntax errors detected».

Шаг 4. Добавьте языковые файлы

Создайте файл lang/ru/install/index.php с переводами строк, которые использует установщик:

<?php
$MESS['MYCOMPANY_CUSTOMAPI_MODULE_NAME'] = 'Название модуля';
$MESS['MYCOMPANY_CUSTOMAPI_MODULE_DESC'] = 'Краткое описание того, что делает модуль';
$MESS['MYCOMPANY_CUSTOMAPI_PARTNER_NAME'] = 'Название компании';

Ключи массива $MESS должны совпадать с теми, что вызываются через Loc::getMessage() в установщике. Префикс ключа обычно повторяет идентификатор модуля заглавными буквами.

Проверка: добавьте в начало файла <?php и убедитесь, что он открывается без ошибок.

Шаг 5. Установите модуль через админку

Откройте раздел «Настройки → Настройки продукта → Модули». В списке доступных для установки должен появиться ваш модуль с названием и описанием из языковых файлов.

Нажмите «Установить». Битрикс вызовет метод DoInstall(), зарегистрирует модуль в таблице b_module и перенаправит обратно в список.

Проверка: в списке установленных модулей должна появиться строка с вашим модулем. Рядом с названием — кнопка «Удалить». Если видите её — установка прошла успешно.

Шаг 6. Проверьте автозагрузку классов

Создайте тестовый класс в lib/Example.php:

<?php

namespace Mycompany\Customapi;

class Example
{
    public static function test()
    {
        return 'Модуль работает';
    }
}

Пространство имён модуля строится по схеме: Vendor\Modulename, где первая буква каждой части заглавная. Путь lib/Example.php соответствует классу \Mycompany\Customapi\Example.

Проверьте вызов в любом PHP-файле сайта после подключения ядра:

<?php
require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

use Mycompany\Customapi\Example;

echo Example::test(); // Должно вывести: Модуль работает

Если вы видите текст «Модуль работает» — автозагрузка настроена правильно, и вы можете добавлять свои классы в lib/.

Если установка не прошла

Типичные ошибки и их причины:

1. «Class mycompany_customapi not found» — файл install/index.php не найден или имя класса не совпадает с vendor_modulename. Убедитесь, что путь и имя класса правильные.
2. Модуль не появляется в списке доступных для установки — проверьте права на папку модуля (должна быть доступна для чтения веб-сервером) и убедитесь, что имя папки совпадает с MODULE_ID.
3. «Call to undefined method» — метод DoInstall или DoUninstall написан с ошибкой в регистре. Битрикс требует именно DoInstall с заглавной D и заглавной I.
4. Класс не автозагружается из lib/ — проверьте пространство имён: оно должно начинаться с заглавных букв и совпадать с именем модуля. Путь lib/Subdirectory/Class.php соответствует \Vendor\Modulename\Subdirectory\Class.
5. Языковые строки не подтягиваются — убедитесь, что перед использованием Loc::getMessage() вызван Loc::loadMessages(__FILE__), и что ключи в $MESS совпадают с аргументами getMessage().

Что делать дальше

После установки модуль готов к добавлению функциональности. Следующие шаги:

• Добавьте страницу настроек в options.php — она появится в разделе модуля в админке;
• Зарегистрируйте обработчики событий в методе DoInstall() через EventManager::getInstance()->registerEventHandler();
• Создайте таблицы базы данных в DoInstall() и удаляйте их в DoUninstall() — используйте \Bitrix\Main\Application::getConnection()->query();
• Добавьте зависимости от других модулей через проверку ModuleManager::isModuleInstalled() в начале DoInstall().

В продакшене следите за версией модуля: при каждом изменении увеличивайте номер в version.php и добавляйте миграции данных, если меняете структуру таблиц.