Word Template Engine:
PHP-шаблонизатор и конвертер документов

Word Template Engine — это шаблонизатор и конвертер документов на PHP, позволяющий создавать документы из шаблонов DOCX (скачать пример.docx), а также конвертировать их через LibreOffice в следующие форматы: PDF, HTML, xHTML, HTML, адаптированный для Email. Эта легковесная библиотека поможет вам в создании счетов, договоров, накладных и прочих документов. Используйте переменные внутри вашего документа и подстановку значений на стороне сервера, заменяйте и удаляйте изображения, работайте с разделами документов (страницами), делайте копии документа или разделов внутри документа, добавляйте ряды к таблицам. Выводите документ в браузер пользователя, прикрепляйте файлы WORD и PDF к электронным письмам или создавайте HTML контент для Email из ваших шаблонов.

Журнал изменений

  • 1.0.1 : 19-07-2021 : Улучшена производительность при обработке больших документов. Подстановка более чем 1000 переменных занимает несколько секунд. Снижено потребление памяти и CPU. Скорость увеличена в 6-8 раз.
  • 1.0.2 : 21-07-2021 : 1) Устранение бага разделителей путей файлов на Windows платформах. 2) Формирование уникальной временной субдиректории для разрешения многопользовательских конфликтов.
  • 1.0.3 : 2023-04-28 : Устранение бага с кодировкой заголовков в браузере Safari при выводе файлов.

Загрузить с GitHub

Установка и использование

#!/bin/bash

# Загрузите и распакуйте последнюю версию
wget 'https://github.com/philip-sorokin/word-template-engine/archive/refs/tags/v1.0.3.tar.gz'
tar xzf 'v1.0.3.tar.gz'

# Установите LibreOffice для конвертации DOCX в PDF, HTML и другие форматы
apt update && apt install libreoffice

<?php

// Подключите библиотеку
require_once 'word-template-engine-1.0.3/WordTemplateEngine.php';

// Подключите класс с примерами WordTemplateEngineExamples, если необходимо
require_once 'word-template-engine-1.0.3/examples/examples.php';

Public методы

__construct ( string $template [, string|null $tmp_path, callable $errorHandler ] )
  • @param $template Полный путь к шаблону .docx
  • @param $tmp_path Опционально. Полный путь к директории временных файлов, в которой создаются рабочие файлы. По умолчанию используется корневая директория сайта или текущая директория.
  • @param $errorHandler Опционально. Функция, переопределяющая стандартный обработчик ошибок. Функция принимает 2 строковых параметра: описание ошибки и уникальный статус ошибки.

Конструктор.

$doc = '/var/www/site.com/template.docx';

/* Пример 1. */
$template = new WordTemplateEngine($doc);

/* Пример 2. Определение временной директории */
$template = new WordTemplateEngine($doc, '/var/www/site.com/tmp');

/* Пример 3. Определение обработчика ошибок */
$template = new WordTemplateEngine($doc, null, 'myErrorHandler');
setValue ( string $varName, string|null $replacement ): void
  • @param $varName Имя переменной.
  • @param $replacement Строка замены.

Замена переменной шаблона на строку значения. Переменная шаблона должна иметь следующий вид ${name}, где 'name' передаётся в качестве аргумента $varName.

/* Пример. */

$varName = 'company_name';
$replacement = 'AddonDev';

$template->setValue($varName, $replacement);
cloneRow ( string $varName, int $cnt ): void
  • @param $varName Якорная переменная.
  • @param $cnt Сколько всего рядов вам необходимо.

Клонирование табличного ряда с якорной переменной. К именам всех переменных внутри ряда, включая якорь, добавляется знак '#' и численное значение нумератора.

Например, вы клонируете ряд с якорной переменной ${key}, содержащий также другие переменные: ${customer}, ${order_id}. В результате, эти переменные заменяются на: ${key#1}, ${customer#1}, ${order_id#1}; ${key#2}, ${customer#2}, ${order_id#2} и т. д.

/* Пример. Создание 3-ёх рядов из одного ряда, содержащего переменную ${product_number}. */

$varName = 'product_number';
$template->cloneRow($varName, 3);

/* Подстановка значений переменных после клонирования ряда */

$template->setValue('product_number#1', 1);
$template->setValue('product_number#2', 2);
$template->setValue('product_number#3', 3);
alternativeSyntax ( bool $bool ): void
  • @param $bool Использовать или нет альтернативный синтакс.

Вызовите этот метод перед подстановкой для использования альтернативного синтаксиса переменных шаблона: ~(name) вместо ${name}. Вы также можете при необходимости переключиться обратно на базовый синтаксис. Используйте альтернативный синтаксис для подстановки переменных в ссылках.

/* Пример. */
$template->alternativeSyntax(true);

// Подстановка значений переменных вида ~(var_name)
$template->setValue('company_website', 'https://разработчик.москва');

// Переключение на базовый синтаксис обратно
$template->alternativeSyntax(false);

// Подстановка значений переменных вида ${var_name}
$template->setValue('company_website', 'https://разработчик.москва');
replaceImage ( int $imageID, string $replacement ): void
  • @param $imageID ID изображения согласно нумератору Word.
  • @param $replacement Путь к новому изображению.

Замена изображения в документе на другое изображение.

/* Пример. Замена временного изображение на изображение подписи. */
$template->replaceImage(2, '/var/www/site.com/uploads/signature.png');
deleteImage ( int $imageID ): void
  • @param $imageID ID изображения согласно нумератору Word.

Удаление элемента изображения в документе вместе с файлом изображения.

/* Пример. Удаление подписи. */
$template->deleteImage(2);
save ( string $destination [, string $format = 'docx' ] ): string
  • @param $destination Путь назначения. Может быть полным и относительным, например '/var/www/newdoc.docx', 'newdoc.pdf'. Корнем относительного пути является временная директория.
  • @param $format Опционально. Формат документа: 'docx' (по умолчанию), 'pdf', 'html', 'xhtml', 'mail' (HTML, адаптированный для Email).
  • @return string Полный путь нового документа.

Создание документа из обработанного шаблона.

/* Пример 1. Создание документа DOCX. */
$template->save('/var/www/site.com/newdoc.docx');

/* Пример 2. Создание PDF документа. */
$template->save('/var/www/site.com/newdoc.pdf', 'pdf');

/* Пример 3. Создание HTML файла. */
$template->save('/var/www/site.com/newdoc.html', 'html');

/* Пример 4. Создание xHTML документа. */
$template->save('/var/www/site.com/newdoc.html', 'xhtml');

/* Пример 5. Использование относительного пути и формирование HTML, альтернативного для Email. */
$fileName = $template->save('newdoc.html', 'mail');
output ( [ string $format = 'docx', string|null $fileName, bool $isAttachment ] ): void
  • @param $format Опционально. Формат документа: 'docx' (по умолчанию), 'pdf', 'html', 'xhtml', 'mail' (HTML, адаптированный для Email).
  • @param $fileName Опционально. Определяет имя файла для загрузки.
  • @param $isAttachment Опционально. Форсирует скачивание документов docx и pdf. По умолчанию docx скачивается, а pdf выводится в браузер.

Создание документа из обработанного шаблона и вывод его в браузер клиента.

/* Пример 1. Вывести на загрузку файл DOCX. */
$template->output('docx', 'Invoice 777');

/* Пример 2. Вывести в браузер файл PDF. */
$template->output('pdf', 'Invoice 777');

/* Пример 3. Вывести на загрузку файл PDF. */
$template->output('pdf', 'Invoice 777', true);
useSection ( int $idx ): void
  • @param $idx Номер раздела.

Удаляет все разделы в документе за исключением раздела, номер которого передан в качестве аргумента. Этот метод сокращает документ до определённого раздела.

Внимание! Метод необходимо вызывать до подстановки значений, т.к. параграфы и табличные ряды кэшируются для лучшей производительности.
Внимание! Если в документе имеются разрывы страниц, следующие за ними страницы должны начинаться с параграфов. Иначе документ может неверно отображаться.

/* Пример. */

// Сначала необходимо удалить все неиспользуемые изображения для сокращения размера результирующего файла.
$template->deleteImage(3);
$template->deleteImage(4);

// Сокращение документа до первой секции.
$template->useSection(1);

$template->setValue('company_name', 'AddonDev');
$template->save('/var/www/site.com/newdoc.docx');
repeat ( [ int $cnt = 1, int $idx ] ): void
  • @param $cnt Опционально. Сколько всего копий необходимо создать. По умолчанию: 1.
  • @param $idx Опционально. Повтор только одного раздела.

Копирование документа один или несколько раз. Если передаётся второй аргумент, копируется только определённая секция и добавляется в конец документа. Внимание! Метод должен вызываться до или после подстановки значений, т.к. параграфы и табличные ряды кэшируются для лучшей производительности. Выбор порядка вызовов зависит от документа.

/* Пример 1. Копирование всего документа 1 раз. */
$template->repeat();

/* Пример 2. Копирование всего документа 2 раза. */
$template->repeat(2);

/* Пример 3. Использование только первого раздела и его копирование. */
$template->useSection(1);
$template->setValue('company_name', 'AddonDev');
$template->repeat(1);
dropMetaData ( ): void

Удаление всех базовых метаданных документа и двух расширенных сойств: "Компания", "Руководитель". После вызова этого метода вы должны переопределить время создания документа, название и автора документа, иначе документ будет повреждён.

/* Пример. */
$template->dropMetaData();
setTitle ( string $title ): void
  • @param $title

Определение базового свойства документа - "Название". Также выводится в качестве заголовка документов, открытых в браузере: PDF, HTML, XHTML.

/* Пример. */
$template->setTitle('Счёт 777');
setAuthor ( string $author ): void
  • @param $author

Определение базового свойства документа - "Автор". Устанавливает автора, очищает свойства "Кем изменено".

/* Пример. */
$template->setAuthor('Пётр Петров');
setTime ( [ string|null $time ] ): void
  • @param $time Опционально. Дата и время в формате ISO 8601. Если неопределено или null, устанавливается текущее время.

Определение времени создания документа. Очищает свойства "Изменено", "Напечатано".

/* Пример 1. Установление текущего времени. */
$template->setTime();

/* Пример 2. Определение другого времени. */
$template->setTime('2021-05-12T13:47:01+03:00');
setCompany ( string $companyName ): void
  • @param $companyName

Определение расширенных метаданных - "Компания".

/* Пример. */
$template->setCompany('AddonDev');
setManager ( string $manager ): void
  • @param $manager

Определение расширенных метаданных - "Руководитель".

/* Пример. */
$template->setManager('Иван Иванов');
setSubject ( string $subject ): void
  • @param $subject

Определение базовых метаданных - "Тема".

/* Пример. */
$template->setSubject('Счёт для Марьи Ивановны');
setKeywords ( string $keywords ): void
  • @param $keywords

Определение базовых метаданных - "Теги".

/* Пример. */
$template->setKeywords('Документы, платёж, заказ');
setDescription ( string $description ): void
  • @param $description

Определение базовых метаданных - "Примечания".

/* Пример. */
$template->setDescription('Примечание документа');
setCategory ( string $category ): void
  • @param $category

Определение базовых метаданных - "Категории".

/* Пример. */
$template->setCategory('Категория');
setStatus ( string $contentStatus ): void
  • @param $contentStatus

Определение базовых метаданных - "Состояние контента".

/* Пример. */
$template->setStatus('Новый');
embedStyleSheet ( string $stylesheet ): void
  • @param $stylesheet

Добавление встроенных стилей CSS в секцию HEAD документа, который будет конвертирован в формат HTML или XHTML.

/* Пример. */
$template->embedStyleSheet('.Table4_E10 {font-weight: bold}');
$template->output('mail');
embedScript ( string $script ): void
  • @param $script

Добавление встроенных скриптов JavaScript в секцию HEAD документа, который будет конвертирован в формат HTML или XHTML.

/* Пример. */
$template->embedScript("console.log('Hello world!')");
$template->output('html');
addStyleSheet ( string $url ): void
  • @param $url

Добавление внешних стилей CSS в секцию HEAD документа, который будет конвертирован в формат HTML или XHTML

/* Пример. */
$template->addStyleSheet('https://site.com/style.css');
$template->output('html');
addScript ( string $url ): void
  • @param $url

Добавление внешних скриптов JavaScript в секцию HEAD документа, который будет конвертирован в формат HTML или XHTML

/* Пример. */
$template->addScript('https://site.com/script.js');
$template->output('html');
sendOutputHeaders ( bool $bool ): void
  • @param $bool

Вызовите этот метод с параметром FALSE в качестве аргумента перед выводом документа, если вы хотите установить свои заголовки.

/* Пример. Установление заголовков перед выводом документа. */
$template->sendOutputHeaders(false);
header('Content-type: application/pdf');
$template->output('pdf');
setOutputFilter ( string $filter ): void
  • @param $filter Параметр фильтра LibreOffice, например 'HTML:EmbedImages'.

Если вам необходимо переопределить фильтр конвертации, установите его перед сохранением / выводом документа.

/* Пример. */
$template->setOutputFilter('HTML:EmbedImages');
$template->output('html');
setLocale ( string $locale ): void
  • @param $locale UNIX локаль.

Локаль, устанавливаемая перед конвертацией шаблона .docx в другие форматы. По умолчанию: 'C.UTF-8'.

/* Пример. */
$template->setLocale('en_US.utf8');
$template->output('html');

Дополнительная информация