Введение и базовые концепции
Модуль Генератор документов documentgenerator создает файлы по шаблонам и данным объектов Bitrix Framework. Модуль подходит для счетов, актов, договоров, коммерческих предложений и других документов, в которых постоянная структура сочетается с изменяемыми значениями.
Разработчик выбирает шаблон и объект, данные которого нужно добавить в документ. Модуль получает значения из этого объекта, подставляет их в поля шаблона и формирует документ. Результат можно сохранить как исходный файл, а при доступном преобразовании — получить в другом формате.
Шаблон + исходный объект + дополнительные значения
-> провайдер данных
-> заполненное тело документа
-> файл документа
Модуль Генератор документов входит в Битрикс24 и отсутствует в стандартной поставке «1С-Битрикс: Управление сайтом».
Когда использовать модуль
Используйте модуль, когда документ должен соответствовать единому шаблону, а значения зависят от данных продукта. Типовые задачи:
-
сформировать документ для объекта CRM или другого объекта продукта,
-
подставить реквизиты, даты, суммы, изображения и списки связанных объектов,
-
повторно создать файл после изменения исходных данных,
-
получить исходный файл, PDF или изображение, если нужное преобразование доступно,
-
расширить набор источников данных собственным провайдером.
Модуль отвечает за шаблоны, подстановку значений и файлы документов. Код, который запускает генерацию, и правила изменения исходного объекта остаются в приложении или в модуле, который использует documentgenerator.
Основные термины
Шаблон — описание будущего документа. Шаблон связывает тело документа с провайдером данных и содержит настройки, по которым модуль распознает поля.
Тело шаблона — исходный файл или другое представление шаблона, которое умеет обрабатывать соответствующий класс Body.
Поле — именованное значение, доступное при заполнении шаблона. Описание поля задает его тип и источник данных.
Плейсхолдер — метка в теле шаблона, которую модуль заменяет значением поля при обработке документа.
Провайдер данных — класс, который описывает доступные поля и получает их значения из исходного объекта. Провайдеры могут возвращать простые значения, связанные объекты и наборы значений.
Значение — объект, который подготавливает данные поля к вставке в шаблон. Обработка зависит от типа данных и может учитывать форматирование.
Документ — объект генерации, который связывает шаблон, исходные данные, пользовательский контекст и созданные файлы.
Хранилище — реализация, которая сохраняет тела шаблонов и файлы документов. Хранилище возвращает данные для дальнейшей работы с ними.
Модель генерации
Основные точки входа зависят от задачи.
|
Задача |
API |
Результат |
|
Проверить доступность генерации |
|
Логическое значение доступности PHP-классов |
|
Получить менеджер провайдеров или хранилище по умолчанию |
Методы |
Менеджер провайдеров или хранилище по умолчанию |
|
Загрузить шаблон и задать класс исходных данных |
|
Объект шаблона с телом, полями и выбранным провайдером |
|
Создать, получить или актуализировать документ |
|
Объект документа и результат файловой операции |
Провайдер данных отделяет шаблон от структуры исходного объекта. Шаблон обращается к полям по именам, а провайдер определяет, откуда получить значения. Благодаря этому один механизм генерации можно использовать для разных типов объектов.
Обработка состоит из шести этапов:
-
Код подключает модуль и проверяет, что генерация доступна.
-
Код выбирает шаблон с нужным типом тела и провайдером данных.
-
Код передает идентификатор или данные исходного объекта и при необходимости дополнительные значения.
-
Провайдер получает значения полей, а классы значений подготавливают их для шаблона.
-
Тело документа заменяет плейсхолдеры и формирует результат.
-
Хранилище сохраняет файл. Дополнительные преобразователи могут подготовить PDF или изображение.
Для работы с конкретным шаблоном или документом используйте классы Template и Document, а не прямые запросы к данным модуля.
Подробнее о связях объектов, этапах сохранения и побочных эффектах — в статье Схема работы генератора документов и основные объекты.
Подключение модуля
Перед обращением к API подключите модуль documentgenerator. Метод Loader::includeModule() возвращает false, если модуль недоступен.
use Bitrix\DocumentGenerator\Driver;
use Bitrix\Main\Loader;
if (!Loader::includeModule('documentgenerator'))
{
throw new \RuntimeException('Модуль documentgenerator не установлен');
}
$driver = Driver::getInstance();
if (!$driver->isEnabled())
{
throw new \RuntimeException('Генератор документов недоступен');
}
Метод Driver::isEnabled() проверяет наличие PHP-классов DOMDocument и ZipArchive. Он не повторяет все проверки установки модуля.
Зависимости модуля
Для установки и обработки шаблонов нужны:
-
PHP-расширение XML, которое предоставляет класс
DOMDocument, -
PHP-расширение ZIP, которое предоставляет класс
ZipArchive, -
установленный модуль
humanresources.
Модуль transformer нужен для преобразования созданного файла в PDF и изображение. Без него можно сформировать и получить исходный файл.
Для хранилища по умолчанию Driver использует модуль disk, если он установлен, или файловое хранилище Bitrix Framework.
Что подготовить для генерации
До запуска основного сценария определите:
-
шаблон и формат его тела,
-
класс провайдера данных,
-
исходный объект, значения которого попадут в документ,
-
пользователя, от имени которого модуль проверит доступ,
-
регион и культуру — настройки формата дат и имен для выбранного языка, если они влияют на результат,
-
дополнительные значения, которые должны заменить данные провайдера,
-
требуемый формат результата и доступность преобразования.
После генерации проверяйте результат каждой операции до обращения к файлу. Ошибка может возникнуть при загрузке шаблона, получении исходных данных, проверке обязательных полей, обработке тела, сохранении или преобразовании.
Создание первого документа
Подготовьте идентификатор существующего шаблона, класс провайдера, исходное значение и идентификатор пользователя. Формат исходного значения зависит от провайдера. Передайте идентификатор объекта или другой поддерживаемый набор данных.
Пример. Загрузите шаблон, сформируйте исходный файл и получите ссылку на скачивание. Передайте в массиве $values значения, которые заменят данные провайдера для соответствующих плейсхолдеров.
use Bitrix\DocumentGenerator\Document;
use Bitrix\DocumentGenerator\Driver;
use Bitrix\DocumentGenerator\Template;
use Bitrix\Main\Loader;
// Перед запуском подготовьте:
// $templateId — идентификатор существующего шаблона
// $providerClass — полное имя класса провайдера данных
// $sourceValue — исходное значение в формате провайдера
// $userId — идентификатор пользователя для проверки доступа
// $values — дополнительные значения полей, например ['DocumentTitle' => 'Счет № 15']
if (!Loader::includeModule('documentgenerator'))
{
throw new \RuntimeException('Модуль documentgenerator не установлен');
}
if (!Driver::getInstance()->isEnabled())
{
throw new \RuntimeException('Расширения PHP XML и ZIP недоступны');
}
// Загрузите шаблон и укажите провайдер данных
$template = Template::loadById($templateId);
if (!$template || $template->isDeleted())
{
throw new \RuntimeException('Шаблон не найден');
}
$template->setSourceType($providerClass);
if (!$template->getSourceType())
{
throw new \RuntimeException('Провайдер данных не поддерживается');
}
// Создайте документ для исходного объекта
$document = Document::createByTemplate($template, $sourceValue);
if (!$document)
{
throw new \RuntimeException('Не удалось создать объект документа');
}
// Передайте пользователя и проверьте его доступ к исходным данным
$document->setUserId($userId);
if (!$document->hasAccess())
{
throw new \RuntimeException('Нет доступа к исходным данным');
}
// Добавьте значения полей и сформируйте исходный файл без преобразования
$document->setValues($values);
$result = $document->getFile(false);
if (!$result->isSuccess())
{
throw new \RuntimeException(implode('; ', $result->getErrorMessages()));
}
// Получите ссылку на сформированный файл
$fileData = $result->getData();
$downloadUrl = $fileData['downloadUrl'] ?? null;
if ((int)$document->FILE_ID <= 0 || !$downloadUrl)
{
throw new \RuntimeException('Исходный файл не сформирован');
}
После успешного вызова массив результата содержит идентификатор документа и ссылку downloadUrl на исходный файл.
Границы PHP API
Серверный PHP API модуля documentgenerator не заменяет:
-
REST API Битрикс24 для внешних интеграций,
-
настройку роботов и бизнес-процессов в интерфейсе продукта,
-
предметные правила CRM, Интернет-магазина или другого модуля,
-
общий API файлов, событий, ORM и компонентов Bitrix Framework.
Если генерацию запускает другой модуль, сначала проверьте доступ к его исходному объекту. Права модуля documentgenerator и доступ провайдера к данным решают разные задачи, поэтому одной проверки может быть недостаточно для всего сценария.
Связанные материалы
Выберите материал по задаче:
-
Схема работы генератора документов и основные объекты — связи шаблона, документа, провайдера, тела и файлов.
-
Шаблоны, поля и форматирование — плейсхолдеры, типы значений, повторяемые блоки и форматирование.
-
Провайдеры данных — получение значений, вложенные поля и собственные провайдеры.
-
Документы — создание, сохранение, обновление и удаление документов.
-
Файлы, форматы и преобразование — исходные файлы, PDF, изображения и публичные ссылки.
-
Права доступа — разрешения на шаблоны и документы и доступ к исходным данным.
-
События и расширение модуля — обработчики жизненного цикла и регистрация собственных реализаций.
-
Встраивание документов в интерфейс — публичный просмотр и собственный компонент для авторизованного пользователя.
-
Производительность и частые ошибки — нагрузка, очередь актуализации и диагностика.
Начните с модели объектов и подготовки шаблона. Затем настройте провайдер данных и переходите к созданию документа. Права, формат результата и обработку ошибок определите до запуска генерации в рабочем сценарии.