Как создать локальный модуль в Bitrix24
Что такое локальный модуль?
Локальный модуль — это расширение Bitrix24, которое живёт в директории /local/modules/. В отличие от решений из маркетплейса, локальный модуль:
- Полностью под вашим контролем
- Не требует публикации
- Может использовать все API ядра Bitrix
- Легко версионировать через Git
Директория /local/modules/ имеет приоритет над /bitrix/modules/. Это позволяет переопределять стандартные модули.
Структура файлов
Каждый модуль следует строгой файловой структуре. Рассмотрим модуль vendor.mymodule:
Имя модуля обязательно должно быть в формате vendor.modulename — через точку, в нижнем регистре.
Пошаговое создание
Этот файл подключается при загрузке модуля. Здесь регистрируем автозагрузчик классов.
Класс-установщик наследуется от CModule. Описывает метаданные и логику install/uninstall.
Массив с версией и датой, который читает ядро Bitrix.
Классы модуля с namespace, подключаемые через автозагрузчик.
include.php
Точка входа модуля — подключается при каждом вызове CModule::IncludeModule('vendor.mymodule'):
<?php
use Bitrix\Main\Loader;
$moduleId = 'vendor.mymodule';
$moduleDir = __DIR__;
// Регистрируем автозагрузчик классов
Loader::registerAutoLoadClasses(
$moduleId,
[
'Vendor\\MyModule\\Helper' => 'lib/Helper.php',
'Vendor\\MyModule\\EventHandler' => 'lib/EventHandler.php',
]
);Вместо ручной регистрации классов можно использовать PSR-4 автозагрузку через Loader::registerNamespace().
install/index.php — установщик
Класс установщика обязательно наследуется от CModule:
<?php
use Bitrix\Main\Localization\Loc;
use Bitrix\Main\ModuleManager;
use Bitrix\Main\EventManager;
Loc::loadMessages(__FILE__);
class vendor_mymodule extends CModule
{
public $MODULE_ID = 'vendor.mymodule';
public function __construct()
{
$arModuleVersion = [];
include __DIR__ . '/version.php';
$this->MODULE_NAME = Loc::getMessage('VENDOR_MYMODULE_NAME');
$this->MODULE_DESCRIPTION = Loc::getMessage('VENDOR_MYMODULE_DESC');
$this->MODULE_VERSION = $arModuleVersion['VERSION'];
$this->MODULE_VERSION_DATE = $arModuleVersion['VERSION_DATE'];
$this->PARTNER_NAME = 'Vendor';
}
public function DoInstall()
{
ModuleManager::registerModule($this->MODULE_ID);
$this->InstallEvents();
}
public function DoUninstall()
{
$this->UnInstallEvents();
ModuleManager::unRegisterModule($this->MODULE_ID);
}
public function InstallEvents()
{
EventManager::getInstance()->registerEventHandler(
'main',
'OnPageStart',
$this->MODULE_ID,
'Vendor\\MyModule\\EventHandler',
'onPageStart'
);
}
public function UnInstallEvents()
{
EventManager::getInstance()->unRegisterEventHandler(
'main',
'OnPageStart',
$this->MODULE_ID,
'Vendor\\MyModule\\EventHandler',
'onPageStart'
);
}
}Имя класса установщика формируется из ID модуля: точка заменяется на _. Для vendor.mymodule — класс vendor_mymodule.
install/version.php
<?php
$arModuleVersion = [
'VERSION' => '1.0.0',
'VERSION_DATE' => '2025-05-20',
];Классы модуля
lib/Helper.php
<?php
namespace Vendor\MyModule;
class Helper
{
public static function formatPhone(string $phone): string
{
$digits = preg_replace('/\D/', '', $phone);
return sprintf(
'+%s (%s) %s-%s-%s',
$digits[0],
substr($digits, 1, 3),
substr($digits, 4, 3),
substr($digits, 7, 2),
substr($digits, 9, 2)
);
}
}lib/EventHandler.php
<?php
namespace Vendor\MyModule;
use Bitrix\Main\EventResult;
class EventHandler
{
public static function onPageStart(): EventResult
{
// Логика при загрузке страницы
return new EventResult(EventResult::SUCCESS);
}
}Языковые файлы
Файл lang/ru/install/index.php:
<?php
$MESS['VENDOR_MYMODULE_NAME'] = 'Мой модуль';
$MESS['VENDOR_MYMODULE_DESC'] = 'Пример локального модуля для Bitrix24';Установка и отладка
Для отладки используйте \Bitrix\Main\Diag\Debug::writeToFile($data, '', '__bx_log.log') — данные запишутся в файл в корне сайта.