Разработка кастомного модуля 1С-Битрикс

Разработка кастомного модуля 1С-Битрикс

Расширение функциональности через правки ядра — худшее, что можно сделать в 1С-Битрикс. После каждого обновления платформы правки слетают, поддержка становится кошмаром, а понять «что и зачем изменено» через год невозможно. Кастомный модуль — правильный способ добавить нестандартную функциональность без вмешательства в ядро.

Архитектура модуля Битрикс

Модуль 1С-Битрикс — это директория в /bitrix/modules/<vendor>.<modulename>/ со строго определённой структурой. Битрикс использует соглашение об именовании: <vendor>.<name>, где vendor — краткое имя разработчика.

vendor.modulename/
├── install/
│   ├── index.php          # Класс установщика (extends CModule)
│   ├── db/
│   │   └── mysql/
│   │       ├── install.sql   # SQL для создания таблиц
│   │       └── uninstall.sql # SQL для удаления таблиц
│   └── files/             # Файлы, копируемые при установке
│       └── bitrix/
│           └── components/
├── lib/                   # Классы в пространстве имён Vendor\Modulename\
│   ├── Repository.php
│   ├── Service.php
│   └── Orm/
│       └── EntityTable.php  # ORM-сущность (D7)
├── lang/
│   ├── ru/
│   │   └── install/
│   │       └── index.php    # Языковые метки
│   └── en/
├── options.php            # Страница настроек модуля
└── include.php            # Подключается при \Bitrix\Main\Loader::includeModule()

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

Установщик наследует CModule и реализует методы DoInstall() и DoUninstall():

// vendor.modulename/install/index.php
class vendor_modulename extends CModule
{
    public string $MODULE_ID          = 'vendor.modulename';
    public string $MODULE_VERSION     = '1.0.0';
    public string $MODULE_NAME        = 'Название модуля';
    public string $MODULE_DESCRIPTION = 'Описание модуля';
    public string $PARTNER_NAME       = 'Vendor';

    public function DoInstall(): void
    {
        RegisterModule($this->MODULE_ID);
        $this->InstallDB();
        $this->InstallFiles();
        $this->InstallEvents();
    }

    public function InstallDB(): void
    {
        global $DB;
        $DB->RunSQLBatch($_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/vendor.modulename/install/db/mysql/install.sql');
    }

    public function InstallEvents(): void
    {
        RegisterModuleDependences(
            'main', 'OnPageStart',
            'vendor.modulename', '\Vendor\Modulename\EventHandlers', 'onPageStart'
        );
    }

    public function DoUninstall(): void
    {
        $this->UnInstallEvents();
        $this->UnInstallDB();
        UnRegisterModule($this->MODULE_ID);
    }
}

ORM D7: работа с данными

Современные модули используют ORM Битрикс D7 вместо прямых SQL-запросов. Класс таблицы объявляется через наследование \Bitrix\Main\ORM\Data\DataManager:

namespace Vendor\Modulename\Orm;

use Bitrix\Main\ORM\Data\DataManager;
use Bitrix\Main\ORM\Fields\{IntegerField, StringField, DatetimeField, BooleanField};

class RequestTable extends DataManager
{
    public static function getTableName(): string
    {
        return 'vendor_modulename_requests';
    }

    public static function getMap(): array
    {
        return [
            new IntegerField('ID', ['primary' => true, 'autocomplete' => true]),
            new StringField('NAME', ['required' => true, 'size' => 255]),
            new StringField('EMAIL', ['size' => 255]),
            new BooleanField('ACTIVE', ['default_value' => true]),
            new DatetimeField('CREATED_AT'),
        ];
    }
}

Использование:

// Получить записи
$result = RequestTable::getList([
    'filter' => ['ACTIVE' => true],
    'select' => ['ID', 'NAME', 'EMAIL'],
    'order'  => ['CREATED_AT' => 'DESC'],
]);

// Добавить запись
RequestTable::add(['NAME' => 'Test', 'EMAIL' => '[email protected]']);

События (Events)

Модуль может подписываться на события платформы и генерировать собственные. Регистрация обработчика события:

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',                    // модуль
    'OnSaleOrderBeforeSaved',  // событие
    ['\Vendor\Modulename\EventHandlers', 'onOrderBeforeSaved']
);

Генерация собственного события для расширяемости:

$event = new \Bitrix\Main\Event('vendor.modulename', 'OnRequestAdded', ['REQUEST' => $request]);
$event->send();

Административный интерфейс

Раздел в административной панели регистрируется через пункт меню (/bitrix/menu.php или автоматически через файл menu.php в папке модуля). Страницы административного раздела располагаются в /bitrix/admin/vendor_modulename_*.php.

Для современных проектов административный интерфейс реализуется как Inertia/React SPA или как классические битриксовые административные страницы с использованием CAdminList, CAdminForm.

Версионирование и Marketplace

Модуль может распространяться через Marketplace 1С-Битрикс. Для публикации требуется: код без ошибок, языковые файлы для ru/en, документация, совместимость с актуальными версиями PHP и платформы.

Типичные сроки разработки

Модуль покрывается документацией на уровне API (PHPDoc) и пользовательской документацией для администраторов.