Блог разработчика 1С-Битрикс
Телефон: Telegram: Email:
SenDev Создание сайтов на 1С-Битрикс

Руководство по работе с классом CModule в 1С-Битрикс

CModule – базовый класс для работы с модулями в 1С-Битрикс. Все модули в системе должны наследоваться от данного класса и располагаться в файле /bitrix/modules/[ID_модуля]/install/index.php. В этой статье мы рассмотрим основные свойства и методы класса CModule, приведём примеры кода и разберём важные нюансы при разработке собственных модулей.

Руководство по работе с классом CModule

Основные свойства класса

Класс CModule имеет ряд важных свойств, которые вы задаёте при создании собственного модуля:

  • MODULE_ID
    Идентификатор модуля (например, iblock или my.module). Должен совпадать с названием каталога модуля.
  • MODULE_VERSION
    Текущая версия модуля (например, 1.0.0).
  • MODULE_VERSION_DATE
    Дата текущей версии модуля (обычно в формате YYYY-MM-DD).
  • MODULE_NAME
    Человекочитаемое название модуля (например, «Модуль работы с информационными блоками»).
  • MODULE_DESCRIPTION
    Краткое описание модуля.
  • MODULE_GROUP_RIGHTS
    Указывает, поддерживает ли модуль схему распределения прав доступа (значение "Y" означает, что модуль поддерживает).

Наследование от CModule

Чтобы создать собственный модуль, необходимо в файле /bitrix/modules/[ID_модуля]/install/index.php объявить класс с именем, совпадающим с ID модуля (точки и дефисы в имени заменяются на нижнее подчеркивание). Например, если модуль называется my.module, то класс следует назвать my_module:

<?php
use \Bitrix\Main\Localization\Loc;

Loc::loadMessages(__FILE__); // Для локализации

class my_module extends CModule
{
    public function __construct()
    {
        $this->MODULE_ID = "my.module";
        $this->MODULE_NAME = "Мой пользовательский модуль";
        $this->MODULE_DESCRIPTION = "Описание моего модуля";
        $this->MODULE_VERSION = "1.0.0";
        $this->MODULE_VERSION_DATE = "2025-01-01";
        $this->MODULE_GROUP_RIGHTS = "Y";
    }

    // Установка модуля
    public function DoInstall()
    {
        global $APPLICATION;
        // Шаг 1. Установка БД, таблиц и пр.
        $this->InstallDB();
        // Шаг 2. Регистрация модуля в системе
        $this->Add(); // или RegisterModule($this->MODULE_ID);
        // Шаг 3. Установка файлов
        $this->InstallFiles();
        // Шаг 4. Установка событий
        $this->InstallEvents();
        // Доп. логика
        $APPLICATION->IncludeAdminFile(
            "Установка модуля: " . $this->MODULE_NAME,
            $_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/my.module/install/step.php"
        );
    }

    // Удаление (деинсталляция) модуля
    public function DoUninstall()
    {
        global $APPLICATION;
        // Шаг 1. Удаление событий
        $this->UnInstallEvents();
        // Шаг 2. Удаление файлов
        $this->UnInstallFiles();
        // Шаг 3. Удаление БД, таблиц
        $this->UnInstallDB();
        // Шаг 4. Удаление модуля из таблицы b_module
        $this->Remove(); // или UnRegisterModule($this->MODULE_ID);
        // Доп. логика
        $APPLICATION->IncludeAdminFile(
            "Деинсталляция модуля: " . $this->MODULE_NAME,
            $_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/my.module/install/unstep.php"
        );
    }

    // Установка БД
    public function InstallDB()
    {
        // Пример. Создание собственной таблицы.
        // global $DB;
        // $DB->RunSQLBatch($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/my.module/install/db/install.sql");
        return true;
    }

    // Удаление БД
    public function UnInstallDB()
    {
        // Пример. Удаление таблицы.
        // global $DB;
        // $DB->RunSQLBatch($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/my.module/install/db/uninstall.sql");
        return true;
    }

    // Установка файлов
    public function InstallFiles()
    {
        // Например, копирование ресурсов модуля
        // CopyDirFiles(
        //     $_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/my.module/install/components",
        //     $_SERVER["DOCUMENT_ROOT"]."/bitrix/components",
        //     true, true
        // );
        return true;
    }

    // Удаление файлов
    public function UnInstallFiles()
    {
        // Удаление установленных ранее файлов при деинсталляции модуля
        return true;
    }

    // Установка событий
    public function InstallEvents()
    {
        // Регистрируем почтовые события, обработчики, пр.
        return true;
    }

    // Удаление событий
    public function UnInstallEvents()
    {
        // Удаляем зарегистрированные обработчики
        return true;
    }

    // Индивидуальная схема распределения прав
    public function GetModuleRightList()
    {
        return [
            "reference_id" => ["D","R","W"],
            "reference"    => [
                "[D] Доступ запрещён",
                "[R] Чтение",
                "[W] Полный доступ"
            ]
        ];
    }
}

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

  1. MODULE_ID всегда указывается точно так же, как в названии каталога модуля, за исключением замен точек/дефисов на подчеркивания при объявлении класса.
  2. Для подключения перевода используется Loc::loadMessages(__FILE__), и далее вы можете работать с языковыми файлами /lang/ru/install/index.php.
  3. Все методы, отвечающие за установку, удаление, копирование файлов и т. д., можно переопределять под свои нужды.

Методы класса CModule

Ниже рассмотрим самые важные методы:

GetList

public static function GetList()
  • Описание: Возвращает список установленных модулей в виде объекта CDBResult.
  • Пример: 
    $rsInstalledModules = CModule::GetList();
while ($arModule = $rsInstalledModules->Fetch())
{
    echo "<pre>";
    print_r($arModule);
    echo "</pre>";
}

GetDropDownList

public static function GetDropDownList($strSqlOrder = "ORDER BY ID")
  • Описание: Возвращает список модулей в виде CDBResult для использования в элементах форм, таких как SelectBox.
  • Параметр:
    • $strSqlOrder — строка с SQL-порядком сортировки (по умолчанию ORDER BY ID – сортировка по возрастанию поля ID).
  • Пример: 
    $rs = CModule::GetDropDownList("ORDER BY ID");
echo SelectBoxFromArray("module_id", $rs, $module_id);

Add

public function Add()
  • Описание: Регистрирует (добавляет) модуль в таблицу b_module.
  • Пример: 
    $m = new CModule;
$m->MODULE_ID = "iblock";
$m->Add();

Remove

public function Remove()
  • Описание: Удаляет регистрационную запись о модуле из базы данных b_module.
  • Пример: 
    function UnRegisterModule($id)
{
    $m = new CModule;
    $m->MODULE_ID = $id;
    $m->Remove();
    CAllMain::DelGroupRight($id);
}

GetModuleRightList

public function GetModuleRightList()
  • Описание: Возвращает массив, описывающий индивидуальную схему распределения прав модуля. Если модуль поддерживает собственную схему (свойство MODULE_GROUP_RIGHTS="Y"), то в классе можно объявить такой метод. Если метод не переопределён, то используется схема по умолчанию.
  • Пример (внутри класса модуля): 
    public function GetModuleRightList()
{
    return [
        "reference_id" => ["D","R","W"],
        "reference"    => [
            "[D] Доступ запрещен",
            "[R] Чтение",
            "[W] Полный доступ"
        ]
    ];
}
  • Использование: 
    $rs = CModule::GetList();
while ($ar = $rs->Fetch())
{
    $MID = $ar["ID"];
    if ($MID != "main")
    {
        include_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/".$MID."/install/index.php");
        if (class_exists($MID))
        {
            $obModule = new $MID;
            if ($obModule->MODULE_GROUP_RIGHTS == "Y")
            {
                if (method_exists($obModule, "GetModuleRightList"))
                    $arRights = $obModule->GetModuleRightList();
                else
                    $arRights = $APPLICATION->GetDefaultRightList();

                echo $MID.": ".SelectBoxFromArray(
                    "RIGHTS_MODULE_".$MID,
                    $arRights,
                    ${"RIGHTS_MODULE_".$MID},
                    "<по умолчанию>"
                );
            }
        }
    }
    else
    {
        // для главного модуля
        $arRights = $APPLICATION->GetMainRightList();
        echo $MID.": ".SelectBoxFromArray(
            "RIGHTS_MODULE_".$MID,
            $arRights,
            ${"RIGHTS_MODULE_".$MID},
            "<по умолчанию>"
        );
    }
}

DoInstall

public function DoInstall()
  • Описание: Запускает процедуру инсталляции модуля. В этом методе обычно вызываются:
    • InstallDB()
    • InstallFiles()
    • RegisterModule($this->MODULE_ID) или $this->Add()
    • InstallEvents()
  • Пример: см. пример класса my_module выше.

DoUninstall

public function DoUninstall()
  • Описание: Запускает процедуру деинсталляции модуля. В этом методе обычно вызываются:
    • UnInstallEvents()
    • UnInstallFiles()
    • UnInstallDB()
    • UnRegisterModule($this->MODULE_ID) или $this->Remove()
  • Пример: см. пример класса my_module выше.

IncludeModule

public static function IncludeModule($module_name)
  • Описание: Проверяет, установлен ли модуль, и если да, подключает его файл /bitrix/modules/[ID_модуля]/include.php. Возвращает true или false.
  • Пример: 
    if (CModule::IncludeModule("iblock"))
{
    // Теперь доступны классы модуля iblock
    // например, CIBlock, CIBlockElement и т.д.
}

IsInstalled

public function IsInstalled()
  • Описание: Проверяет, установлен ли модуль (по наличию записи в b_module). Возвращает true, если установлен, иначе false.
  • Пример: 
    $obModule = new my_module;
if ($obModule->IsInstalled())
{
    echo "Модуль установлен!";
}
else
{
    echo "Модуль не установлен!";
}

Типичный сценарий установки модуля

  1. Создаёте в /bitrix/modules/my.module/install/index.php класс my_module, наследуемый от CModule.
  2. Переопределяете нужные методы: InstallDB(), InstallFiles(), InstallEvents(), DoInstall() и т.д.
  3. В админке или вручную вызываете процедуру установки, например: 
    include_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/my.module/install/index.php");
$obModule = new my_module;
if (!$obModule->IsInstalled())
{
    $obModule->DoInstall(); // установка модуля
}
  4. После выполнения DoInstall() ваш модуль зарегистрируется в системе, загрузит все необходимые файлы и будет готов к использованию.

Типичный сценарий удаления модуля

  1. В том же файле /bitrix/modules/my.module/install/index.php вы уже определили метод DoUninstall().
  2. Для удаления модуля в админке или скрипте вызываете: 
    include_once($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/my.module/install/index.php");
$obModule = new my_module;
if ($obModule->IsInstalled())
{
    $obModule->DoUninstall();
}
  3. После выполнения DoUninstall() будут удалены настройки, файлы, таблицы БД (при необходимости) и модуль будет исключён из b_module.

Часто используемые функции и классы

  • RegisterModule($moduleID)
    Регистрирует модуль в b_module. Аналогично вызову $module->Add();
  • UnRegisterModule($moduleID)
    Удаляет модуль из b_module. Аналогично $module->Remove();
  • \Bitrix\Main\Loader
    Современный класс для подключения модулей. Метод \Bitrix\Main\Loader::includeModule("my.module") эквивалентен CModule::IncludeModule("my.module").
  • CMain::GetUserRight($moduleID)
    Проверяет права текущего пользователя на указанный модуль.
  • CMain::DelGroupRight($moduleID)
    Сбрасывает права доступа для всех групп для заданного модуля.

Полезные советы по разработке модулей

  1. Правильное именование
    Убедитесь, что название модуля (ID) уникально и понятно. Если ваш модуль называется my.module, каталог и все настройки должны быть последовательны (каталог my.module, класс my_module).
  2. Соблюдайте структуру папок
    Часто в структуре модуля создают папки:
    • /install/components – для компонентов,
    • /install/db – для SQL-скриптов установки/удаления таблиц,
    • /install/admin – для административных страниц,
    • /install/js – для JavaScript-файлов и т. д.
  3. Локализация
    Храните все тексты, выводимые пользователю, в языковых файлах, чтобы легко переводить модуль на другие языки.
  4. Проверка совместимости
    Учитывайте версии ядра Битрикс. Некоторые методы могут меняться, особенно при переходе на D7.
  5. Отладка
    • Включайте отображение ошибок и логируйте процесс инсталляции/деинсталляции, чтобы было проще искать проблемы.
    • При ошибках установки/удаления не забудьте корректно «откатить» все внесённые изменения (файлы, таблицы, события).

Заключение

Класс CModule – это фундамент для создания собственных модулей в 1С-Битрикс. Понимание принципов наследования, структуры каталога модуля и правильной реализации методов установки/удаления обеспечит вам удобную интеграцию ваших решений в систему. Используйте приведённые примеры и не забывайте документировать свой код, чтобы впоследствии было проще вносить изменения и поддерживать модуль в актуальном состоянии.

Надеемся, это руководство поможет вам быстрее освоить разработку модулей на базе 1С-Битрикс, а примеры кода станут основой для ваших собственных решений. Удачного кодинга!

Теги:  CModule, разработка модулей, PHP, установка модулей, деинсталляция модулей
Предупреждение / Disclaimer

Похожие статьи

Стоимость услуг по разработке и сопровождению сайтов на 1C-Битрикс

Лендинг

от 3 дней

от 25 000 рублей

Разработка одностраничного сайта на платформе Битрикс

* стоимость зависит от наличия верстки, использования готового решения и т.д.

Разработка интернет-магазина с готовой версткой

от 4 недель

от 90 000 рублей

* указана минимальная стоимость. Стоимость выбранной лицензии «1С-Битрикс» оплачивается отдельно.

Техническая поддержка

выполняется с сайтами на основе любых CMS

от 5 000 рублей
Оптимизация производительности действующих интернет-проектов, наполнение и сопровождение, полная техническая поддержка и продвижение в поисковых сетях.

* стоимость зависит от объема и сложности выполняемых работ, используемой CMS.

Смотреть все цены »