Search by

teclor / bitrix-module-utils

Teclor

Утилиты для инсталляции и использования модулей Битрикс

Package info

github.com/Teclor/bitrix-module-utils

pkg:composer/teclor/bitrix-module-utils

Statistics

Installs: 42

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

1.3.1 2026-10-20 19:44 UTC

This package is auto-updated.

Last update: 2026-11-07 22:52:11 UTC


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 по-прежнему падает при отсутствии пакета. Чтобы перейти на композицию:

  1. Уберите use InstallerTrait; из класса.
  2. Замените $this->initModule() в конструкторе на блок с getInstaller() и fallback из примера выше.
  3. Добавьте методы DoInstall(), DoUninstall(), GetModuleRightList() и getInstaller().
  4. Методы 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. Можно также использовать для ошибок в процессе выполнения задач.