Структура, install/index.php, установка и удаление

Где хранить модуль

Для своих доработок обычно используется папка /local/modules. Например:

/local/modules/test.example/

ID модуля лучше делать в формате vendor.module: коротко, латиницей, без пробелов. Например: test.chatsearch, test.multiscrum, local.crmtools.

Минимальная структура

/local/modules/test.example/
├── include.php
├── options.php
├── default_option.php
├── install/
│   ├── index.php
│   ├── version.php
│   ├── components/
│   ├── js/
│   ├── css/
│   └── db/
│       └── mysql/
│           ├── install.sql
│           └── uninstall.sql
└── lib/
    ├── Service/
    │   └── ExampleService.php
    ├── Model/
    │   └── ExampleTable.php
    └── Controller/
        └── Example.php

Не все папки обязательны. Если модуль не создаёт таблицы, не нужны SQL-файлы. Если нет публичных JS/CSS, не нужны папки install/js и install/css.

Что за что отвечает

Класс установщика

Имя класса установщика обычно повторяет ID модуля, но точка заменяется на подчёркивание: test.example → test_example.

<?php

use Bitrix\Main\Application;
use Bitrix\Main\ModuleManager;

class test_example extends CModule
{
    public $MODULE_ID = 'test.example';
    public $MODULE_NAME = 'Пример модуля';
    public $MODULE_DESCRIPTION = 'Рабочий пример локального модуля';
    public $PARTNER_NAME = 'IT-Solution';
    public $PARTNER_URI = 'https://example.local';

    /**
     * Заполняет версию модуля.
     */
    public function __construct()
    {
        $version_file = __DIR__ . '/version.php';

        if (file_exists($version_file)) {
            $arModuleVersion = [];
            include $version_file;

            $this->MODULE_VERSION = $arModuleVersion['VERSION'] ?? '1.0.0';
            $this->MODULE_VERSION_DATE = $arModuleVersion['VERSION_DATE'] ?? '2026-01-01 00:00:00';
        }
    }
}

Для новых PHP-версий нужен именно __construct(), а не старый конструктор вида function test_example().

DoInstall и DoUninstall

DoInstall() вызывается при установке, DoUninstall() — при удалении.

/**
 * Устанавливает модуль.
 */
public function DoInstall(): void
{
    global $APPLICATION;

    $this->installDb();
    $this->installFiles();
    $this->installEvents();

    ModuleManager::registerModule($this->MODULE_ID);

    $APPLICATION->IncludeAdminFile(
        'Установка модуля ' . $this->MODULE_NAME,
        __DIR__ . '/step.php'
    );
}

/**
 * Удаляет модуль.
 */
public function DoUninstall(): void
{
    global $APPLICATION;

    $this->uninstallEvents();
    $this->uninstallFiles();
    $this->uninstallDb();

    ModuleManager::unRegisterModule($this->MODULE_ID);

    $APPLICATION->IncludeAdminFile(
        'Удаление модуля ' . $this->MODULE_NAME,
        __DIR__ . '/unstep.php'
    );
}

installDb и uninstallDb

Если модуль создаёт свои таблицы, это можно сделать через SQL-файлы или через ORM. Простой вариант — выполнить SQL из папки install/db/mysql.

/**
 * Создаёт таблицы модуля.
 */
public function installDb(): bool
{
    $connection = Application::getConnection();
    $sql_file = __DIR__ . '/db/mysql/install.sql';

    if (file_exists($sql_file)) {
        $connection->executeSqlBatch(file_get_contents($sql_file));
    }

    return true;
}

/**
 * Удаляет таблицы модуля.
 */
public function uninstallDb(): bool
{
    $connection = Application::getConnection();
    $sql_file = __DIR__ . '/db/mysql/uninstall.sql';

    if (file_exists($sql_file)) {
        $connection->executeSqlBatch(file_get_contents($sql_file));
    }

    return true;
}

В свежем коде часто удобнее делать миграции через PHP-классы, а не хранить всю логику в install.sql.

installFiles и uninstallFiles

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

/**
 * Копирует публичные файлы модуля.
 */
public function installFiles(): bool
{
    CopyDirFiles(
        __DIR__ . '/js',
        $_SERVER['DOCUMENT_ROOT'] . '/local/js/' . $this->MODULE_ID,
        true,
        true
    );

    CopyDirFiles(
        __DIR__ . '/css',
        $_SERVER['DOCUMENT_ROOT'] . '/local/css/' . $this->MODULE_ID,
        true,
        true
    );

    return true;
}

/**
 * Удаляет публичные файлы модуля.
 */
public function uninstallFiles(): bool
{
    DeleteDirFilesEx('/local/js/' . $this->MODULE_ID);
    DeleteDirFilesEx('/local/css/' . $this->MODULE_ID);

    return true;
}

Установить модуль

1. Положить модуль в /local/modules/test.example.
2. Открыть админку.
3. Перейти в раздел модулей.
4. Найти модуль по названию.
5. Нажать «Установить».

Если модуль не появился, сначала проверь путь, имя класса в install/index.php и значение MODULE_ID.

Удалить модуль

Удаление должно откатить то, что было создано установкой: события, публичные файлы, таблицы, агенты, права и настройки.

Если таблицы с данными удалять опасно, можно сделать параметр «сохранить данные» на шаге удаления. Это лучше вынести в отдельную логику, а не удалять таблицы всегда.

Частые ошибки

• Официальный курс: структура файлов модуля
• Официальный курс: структура полной сборки модуля
• Официальный курс: переход на PHP 8.x