teclor / bitrix-module-utils
Утилиты для инсталляции и использования модулей Битрикс
Requires
- php: >=8.2
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Набор классов, моделей и хелперов для упрощения разработки, инсталляции и управления настройками модулей 1С-Битрикс. Пакет инкапсулирует рутинную логику создания установочных скриптов, регистрации событий, выполнения миграций и формирования настроек.
Для полноценного погружения во все возможности пакета изучайте исходники.
Архитектура и возможности
- Установка в один клик: класс
Installerберет на себя вызов необходимых хелперов (Файлы, БД, Зависимости, События, Composer) на основе декларативного списка задач. - Управление событиями: регистрация через строго типизированные DTO-модели
EventModelиOrmEventModel. - Миграции: итератор миграций автоматически находит и выполняет классы, реализующие
ModuleMigrationInterface. - Страница настроек: класс
Optionsпозволяет генерироватьoptions.phpбез дублирования HTML-кода вкладок. - Административное меню: конструктор
MenuItemдляadmin/menu.php. - Обработка ошибок: иерархия исключений, наследуемая от
ModuleException, включающаяNotFoundException,FileNotFoundException,ClassNotFoundExceptionиInstallDutyException.
Установка
Пакет указывается в composer.json модуля, а сам модуль устанавливается в проект через composer. В итоге пакет оказывается в общем vendor проекта.
1. composer.json модуля
{
"name": "vendor/name",
"type": "bitrix-d7-module",
"require": {
"php": ">=8.2",
"composer/installers": "^2.0",
"teclor/bitrix-module-utils": "^1.3"
}
}
Тип bitrix-d7-module и composer/installers кладут модуль в bitrix/modules/vendor.name. Чтобы модуль попадал в local/modules, в composer.json проекта укажите "extra": {"bitrix-dir": "local"}.
Готовая заготовка: stubs/composer.json.
2. Подключение автолоадера composer в Битриксе
Классы пакета должны быть доступны до того, как Битрикс подключит install/index.php модуля, в том числе на странице списка модулей. Подключите автолоадер проекта одним из способов:
-
через
bitrix/.settings.php(Битрикс сам подключитvendor/autoload.php, лежащий рядом с указаннымcomposer.json):'composer' => [ 'value' => ['config_path' => '/local/composer.json'], ],
-
или в
local/php_interface/init.php:require_once $_SERVER['DOCUMENT_ROOT'] . '/local/vendor/autoload.php';
Задача InstallDutiesEnum::COMPOSER в этом сценарии не нужна: она запускает composer install в папке модуля и предназначена для модулей с собственным vendor.
Защита от отсутствия пакета
Битрикс подключает install/index.php каждого модуля из папки modules, когда строит список модулей в админке, даже если модуль не установлен. PHP проверяет use Trait, extends и implements прямо при объявлении класса. Поэтому если пакет не установлен (не выполнен composer install, не подключен автолоадер, пакет удалили из composer.json), строка use InstallerTrait; в index.php роняет всю страницу ошибкой Trait "Module\Utils\Traits\InstallerTrait" not found.
Ссылки на классы внутри тел методов PHP разрешает только при вызове метода. На этом строятся правила:
| Файл | Когда подключается | Что делать |
|---|---|---|
install/index.php |
список модулей, установка и удаление | Installer через композицию, без use/extends/implements классов пакета |
admin/menu.php |
каждая страница админки, если модуль установлен | if (!class_exists(MenuItem::class)) return false; |
include.php |
Loader::includeModule() |
if (!class_exists(AbstractModule::class)) return false; |
options.php |
страница настроек модуля | вывести CAdminMessage и выйти |
Импорты use Module\Utils\...; в начале файла, типы свойств и параметров и Installer::class безопасны: автозагрузку они не вызывают.
Все заготовки лежат в папке stubs/. Скопируйте их в модуль и замените vendor.name / vendor_name / Vendor\Name на свои значения.
Примеры использования
1. Базовый класс модуля (lib/module.php)
В папке lib/ создайте основной класс модуля, наследующий AbstractModule. По умолчанию Installer ищет его именно в файле lib/module.php.
namespace Vendor\Name; use Module\Utils\AbstractModule; class Module extends AbstractModule { public static function getModuleVersion(): string { return '1.0.0'; } public static function getModuleVersionDate(): string { return '2026-01-01'; } public static function getModuleName(): string { return 'Мой модуль'; } public static function getModuleDescription(): string { return 'Описание функционала модуля'; } public static function getRequiredModuleNames(): array { return ['iblock', 'highloadblock']; } }
2. Инсталлятор (install/index.php)
Класс установщика наследует только CModule, а Installer создаётся лениво и только если пакет загружен. Если пакета нет, модуль остаётся в списке с подсказкой в описании, а установка возвращает понятную ошибку вместо фатальной.
Задачи установки и события Installer берёт из методов getInstallDuties(), getEvents() и getOrmEvents() объекта модуля, если они объявлены. Класс модуля можно передать явно вторым аргументом: new Installer($this, \Vendor\Name\Module::class).
<?php use Module\Utils\Install\InstallDutiesEnum; use Module\Utils\Install\Installer; use Module\Utils\Models\EventModel; use Module\Utils\Models\OrmEventModel; class vendor_name extends CModule { public $MODULE_ID = 'vendor.name'; private const NO_PACKAGE_ERROR = 'Не найден пакет teclor/bitrix-module-utils. Выполните composer install в корне проекта.'; private ?Installer $installer = null; public function __construct() { if ($installer = $this->getInstaller()) { $installer->fillModuleInfo(); return; } // Пакет не загружен: модуль остаётся в списке, админка не падает $this->MODULE_NAME = $this->MODULE_ID; $this->MODULE_DESCRIPTION = self::NO_PACKAGE_ERROR; } public function DoInstall() { if (!$installer = $this->getInstaller()) { $GLOBALS['APPLICATION']->ThrowException(self::NO_PACKAGE_ERROR); return false; } return $installer->install(); } public function DoUninstall() { if (!$installer = $this->getInstaller()) { $GLOBALS['APPLICATION']->ThrowException(self::NO_PACKAGE_ERROR); return false; } $installer->uninstall(); return true; } public function GetModuleRightList() { return class_exists(Installer::class) ? Installer::getDefaultModuleRightList() : false; } public function getInstallDuties(): array { // Указываем, какие шаги нужны при установке return [ InstallDutiesEnum::MODULES, InstallDutiesEnum::SQL, InstallDutiesEnum::MIGRATIONS, InstallDutiesEnum::ADMIN, InstallDutiesEnum::FILES, InstallDutiesEnum::EVENTS, InstallDutiesEnum::ORM_EVENTS, ]; } public function getEvents(): array { return [ new EventModel( fromModuleId: 'main', eventType: 'OnAfterUserAdd', toModuleId: $this->MODULE_ID, toClass: \Vendor\Name\Handlers\UserHandler::class, toMethod: 'onAfterUserAdd' ) ]; } public function getOrmEvents(): array { return [ new OrmEventModel( entity: \Bitrix\Main\UserTable::class, eventType: \Bitrix\Main\ORM\Data\DataManager::EVENT_ON_BEFORE_UPDATE, toModuleId: $this->MODULE_ID, toClass: \Vendor\Name\Handlers\UserHandler::class, toMethod: 'onBeforeUserUpdate' ) ]; } private function getInstaller(): ?Installer { if ($this->installer === null && class_exists(Installer::class)) { $this->installer = new Installer($this); } return $this->installer; } }
Если MODULE_ID не задан, он вычисляется из имени класса: vendor_name → vendor.name.
Также можно использовать методы createEventModel и createOrmEventModel класса Module\Utils\Install\Events для создания моделей событий.
Доступные задачи InstallDutiesEnum:
| Задача | Установка | Удаление |
|---|---|---|
MODULES |
проверка и установка модулей из getRequiredModuleNames() |
— |
COMPOSER |
composer install в папке модуля (только для модулей с собственным vendor) |
— |
ADMIN |
файлы-прокси в /bitrix/admin для файлов из admin/ модуля (кроме menu.php) |
удаление прокси |
FILES |
копирование папок из install/ в корень сайта (кроме db и migrations) |
удаление скопированных файлов |
EVENTS |
регистрация событий из getEvents() |
снятие регистрации |
ORM_EVENTS |
регистрация ORM-событий из getOrmEvents() |
снятие регистрации |
SQL |
install/db/install.sql |
install/db/uninstall.sql |
MIGRATIONS |
up() миграций из install/migrations |
down() миграций |
Если есть задачи SQL или MIGRATIONS, удаление идёт в 2 шага: сначала показывается форма с выбором «сохранить данные».
Удаление выполняет задачи в порядке, обратном установке; миграции откатываются тоже в обратном порядке. Если установка прервалась на какой-то задаче, уже выполненные задачи откатываются, регистрация модуля снимается, а пользователь видит исходную ошибку.
3. Переход с InstallerTrait
Module\Utils\Traits\InstallerTrait оставлен для обратной совместимости и теперь делегирует работу Installer, но помечен как @deprecated: с ним index.php по-прежнему падает при отсутствии пакета. Чтобы перейти на композицию:
- Уберите
use InstallerTrait;из класса. - Замените
$this->initModule()в конструкторе на блок сgetInstaller()и fallback из примера выше. - Добавьте методы
DoInstall(),DoUninstall(),GetModuleRightList()иgetInstaller(). - Методы
getInstallDuties(),getEvents()иgetOrmEvents()оставьте без изменений.
Если вы переопределяли getHelper(), getHelperInstance() или обращались к $this->moduleClass, используйте $this->getInstaller()->getHelper() и $this->getInstaller()->getModuleClass().
4. Миграции базы данных
Поместите классы миграций в директорию install/migrations/. Класс должен реализовывать интерфейс ModuleMigrationInterface.
namespace Vendor\Name\Install\Migrations; use Bitrix\Main\Result; use Module\Utils\Contracts\ModuleMigrationInterface; class AddBooksIblockMigration implements ModuleMigrationInterface { public function getOrderIndex(): int { return 100; } public function up(): Result { // Логика применения return new Result(); } public function down(): Result { // Логика отката return new Result(); } }
Миграции подключаются только во время установки и удаления, когда пакет уже загружен, поэтому implements здесь безопасен.
Миграции выполняются в порядке возрастания getOrderIndex(), а откатываются в обратном порядке. Если up() или down() вернёт Result с ошибками, установка или удаление прервётся с этой ошибкой.
Пакет не зависит от сторонних модулей миграций: внутри up()/down() можно использовать любой API. Например, хелперы модуля sprint.migration сокращают код работы с инфоблоками, HL-блоками, пользовательскими полями и т.п. В этом случае добавьте sprint.migration в getRequiredModuleNames() класса модуля и задачу InstallDutiesEnum::MODULES в getInstallDuties(), чтобы установка проверяла его наличие.
namespace Vendor\Name\Install\Migrations; use Bitrix\Main\Error; use Bitrix\Main\Loader; use Bitrix\Main\Result; use Module\Utils\Contracts\ModuleMigrationInterface; use Sprint\Migration\HelperManager; class AddBooksIblockMigration implements ModuleMigrationInterface { public function getOrderIndex(): int { return 100; } public function up(): Result { return $this->run(function (HelperManager $helper) { $helper->Iblock()->saveIblockType([ 'ID' => 'library', 'LANG' => ['ru' => ['NAME' => 'Библиотека']], ]); $helper->Iblock()->saveIblock([ 'IBLOCK_TYPE_ID' => 'library', 'CODE' => 'books', 'NAME' => 'Книги', 'LID' => ['s1'], ]); }); } public function down(): Result { return $this->run(function (HelperManager $helper) { $helper->Iblock()->deleteIblockIfExists('books', 'library'); }); } private function run(callable $callback): Result { $result = new Result(); try { Loader::requireModule('sprint.migration'); $callback(HelperManager::getInstance()); } catch (\Throwable $e) { $result->addError(new Error($e->getMessage())); } return $result; } }
5. Страница настроек (options.php)
Используйте класс Options для построения интерфейса управления параметрами. Код размещается в корне модуля в файле options.php.
<?php defined('B_PROLOG_INCLUDED') || die(); use Bitrix\Main\Loader; use Module\Utils\Options; use Vendor\Name\Module; if (!class_exists(Options::class)) { require_once $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_admin_after.php'; CAdminMessage::ShowMessage('Не найден пакет teclor/bitrix-module-utils. Выполните composer install в корне проекта.'); return; } $moduleId = Module::getModuleId(); Loader::requireModule($moduleId); $options = new Options($moduleId); $options ->addTab( div: 'main_settings', tab: 'Основные настройки', title: 'Настройка интеграции', options: [ ['api_key', 'API Ключ', '', ['text', 50]], ['use_cache', 'Использовать кеширование', 'Y', ['checkbox']], ] ) ->addRightsTab(); $options->process();
6. Подключение зависимых модулей (include.php)
Чтобы при установке проверялись зависимые модули, а при подключении модуля (например, в include.php) подключались все его зависимости, реализуйте в классе Vendor\Name\Module (наследнике Module\Utils\AbstractModule) метод getRequiredModuleNames() и возвращайте в нём id нужных модулей Битрикса.
public static function getRequiredModuleNames(): array { return ['highloadblock']; }
Подключить все эти модули можно методом Vendor\Name\Module::requireModules(). В include.php предварительно проверьте наличие пакета: если include.php вернёт false, Loader::includeModule() тоже вернёт false вместо фатальной ошибки.
<?php use Module\Utils\AbstractModule; use Vendor\Name\Module; if (!class_exists(AbstractModule::class)) { return false; } Module::requireModules();
7. Административное меню (admin/menu.php)
menu.php установленного модуля подключается на каждой странице админки, поэтому проверка наличия пакета здесь обязательна.
<?php use Module\Utils\Install\MenuItem; if (!class_exists(MenuItem::class)) { return false; } // Проверка прав, если требуется скрыть меню для пользователей без прав на модуль // $moduleRight = $APPLICATION->GetGroupRight('vendor.testmodule'); // if ($moduleRight < 'R') { return false; } $menu = MenuItem::make('Мой крутой модуль', 100) ->setParentMenu('global_menu_settings') // Привязка к глобальному разделу "Настройки" ->setItemsId('vendor_testmodule_root') ->setIcon('sys_menu_icon') ->setPageIcon('sys_page_icon') ->setModuleId('vendor.testmodule') // Авто-скрытие пункта при отсутствии прав на модуль ->addItem( MenuItem::make('Список сущностей', 10) ->setUrl('vendor_testmodule_list.php?lang=' . LANGUAGE_ID) ->addMoreUrl('vendor_testmodule_edit.php') // Подсвечивать пункт при нахождении на странице редактирования ->setTitle('Управление записями модуля') ) ->addItem( MenuItem::make('Вложенный справочник', 20) ->setIcon('default_menu_icon') ->setItemsId('vendor_testmodule_sub') ->addItem( MenuItem::make('Справочник 1', 10)->setUrl('vendor_testmodule_dict1.php?lang=' . LANGUAGE_ID) ) ->addItem( MenuItem::make('Справочник 2', 20)->setUrl('vendor_testmodule_dict2.php?lang=' . LANGUAGE_ID) ) ); return $menu->toArray();
Исключения (Exceptions)
Пакет предоставляет набор исключений для безопасной работы хелперов установки.
ModuleException— базовое исключение, хранит путь к модулю.NotFoundException— базовое исключение для ненайденных сущностей.FileNotFoundException— выбрасывается, если требуемый файл отсутствует на диске.ClassNotFoundException— выбрасывается, если файл подключен, но искомый класс в нем отсутствует.InstallDutyException— возникает при передаче неизвестной задачи вgetInstallDuties. Можно также использовать для ошибок в процессе выполнения задач.