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

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

Генерация документов — счетов, актов, договоров, накладных — встречается в каждом втором проекте на Битрикс. Стандартных инструментов для этого нет: ни в sale, ни в crm. Задачу обычно решают «на коленке» через phpWord или вообще вручную. Модуль даёт системный подход: шаблоны, переменные, версионирование, подписи.

Где это нужно

Типичные сценарии: автоматический счёт после оформления заказа в интернет-магазине, договор при регистрации пользователя в B2B-разделе, акт выполненных работ по закрытой сделке CRM, коммерческое предложение для менеджера. В каждом случае документ должен формироваться мгновенно, содержать актуальные данные и выглядеть профессионально.

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

Модуль vendor.docgen со следующими таблицами:

• b_vendor_docgen_template — шаблоны документов: id, name, type (order/contract/act/offer), format (docx/pdf), template_file, variables_schema, version, is_active
• b_vendor_docgen_document — сгенерированные документы: id, template_id, entity_type, entity_id, file_id (в b_file), status, generated_at, generated_by
• b_vendor_docgen_variable — зарегистрированные переменные: name, source_class, description

Система переменных

Каждая переменная в шаблоне обёрнута двойными фигурными скобками: {{ORDER_NUMBER}}, {{CLIENT_NAME}}, {{ITEMS_TABLE}}. Переменные регистрируются через провайдеры:

class OrderVariableProvider implements VariableProviderInterface
{
    public function getVariables(int $entityId): array
    {
        $order = \Bitrix\Sale\Order::load($entityId);
        $props = $order->getPropertyCollection();

        return [
            'ORDER_NUMBER'   => $order->getField('ACCOUNT_NUMBER'),
            'ORDER_DATE'     => $order->getDateInsert()->format('d.m.Y'),
            'ORDER_SUM'      => number_format($order->getPrice(), 2, ',', ' '),
            'ORDER_CURRENCY' => $order->getCurrency(),
            'CLIENT_NAME'    => $props->getPayerName(),
            'CLIENT_INN'     => $props->getUserProp('INN')?->getValue(),
            'CLIENT_ADDRESS' => $props->getAddress(),
            'ITEMS_TABLE'    => $this->buildItemsTable($order->getBasket()),
        ];
    }
}

Провайдеры регистрируются в настройках модуля и автоматически подставляются при генерации в зависимости от типа документа.

Генерация DOCX

Шаблоны Word обрабатываются через PhpWord:

$templateProcessor = new \PhpOffice\PhpWord\TemplateProcessor($templatePath);

foreach ($variables as $name => $value) {
    if (is_array($value)) {
        // Таблица — клонируем строки
        $templateProcessor->cloneRow('ITEM_NAME', count($value));
        foreach ($value as $i => $item) {
            $templateProcessor->setValue("ITEM_NAME#{$i}", $item['name']);
            $templateProcessor->setValue("ITEM_QTY#{$i}", $item['quantity']);
            $templateProcessor->setValue("ITEM_PRICE#{$i}", $item['price']);
        }
    } else {
        $templateProcessor->setValue($name, htmlspecialchars($value));
    }
}

$outputPath = '/upload/vendor_docgen/' . uniqid() . '.docx';
$templateProcessor->saveAs($outputPath);

Конвертация в PDF

DOCX генерируется быстро, но клиент часто хочет PDF. Конвертация — самое болезненное место. Варианты:

• LibreOffice в headless-режиме: libreoffice --headless --convert-to pdf file.docx — лучшее качество, требует установки на сервер
• PhpSpreadsheet + мPDF — для документов на основе HTML-шаблонов, проще в управлении стилями
• DocRaptor / PDF Rocket — облачные сервисы, не требуют ПО на сервере

Выбор конвертора — параметр в настройках модуля. По умолчанию: mPDF для HTML-шаблонов, LibreOffice для DOCX.

HTML-шаблоны

Альтернатива Word-шаблонам — HTML с CSS. Проще поддерживать, нет проблем с кодировками. Шаблон хранится прямо в b_vendor_docgen_template в поле html_template, переменные подставляются через простой поиск-замену или через Twig:

$loader = new \Twig\Loader\ArrayLoader(['doc' => $template['HTML_TEMPLATE']]);
$twig = new \Twig\Environment($loader);
$html = $twig->render('doc', $variables);

// Конвертация в PDF через mPDF
$mpdf = new \Mpdf\Mpdf(['mode' => 'utf-8', 'format' => 'A4']);
$mpdf->WriteHTML($html);
$mpdf->Output($outputPath, 'F');

Хранение и доступ

Готовый файл сохраняется через \CFile::SaveFile() в таблицу b_file — стандартный механизм Битрикс. Ссылка для скачивания генерируется через \CFile::GetPath(). В b_vendor_docgen_document хранится file_id и метаданные.

Доступ к документу проверяется по принадлежности: пользователь может скачать документ, связанный с его заказом или профилем. Менеджеры CRM — документы своих сделок. Администраторы — все.

Автоматическая генерация по событиям

Документ можно генерировать автоматически при наступлении события Битрикс:

// В init.php или через обработчик в инсталляторе модуля
AddEventHandler('sale', 'OnSaleOrderPaid', ['\Vendor\DocGen\EventHandler', 'onOrderPaid']);

// В классе обработчика
public static function onOrderPaid(\Bitrix\Main\Event $event): void
{
    $orderId = $event->getParameter('id');
    DocGenerator::generate('invoice', 'sale_order', $orderId);
    // → автоматически прикрепляет документ к заказу и отправляет покупателю
}

Сроки разработки

Итого: 12 рабочих дней. Сложная вёрстка документов с колонтитулами, подписями и печатями — +2 дня.