Миграция с DomPDF
Это руководство поможет вам мигрировать с DomPDF (dompdf/dompdf) на TCPDF-Next. Две библиотеки имеют принципиально разные философии проектирования — DomPDF является рендерером HTML/CSS-в-PDF, тогда как TCPDF-Next — это PDF-нативная библиотека с мощным движком рендеринга HTML.
Подход DomPDF vs подход TCPDF-Next
DomPDF рассматривает генерацию PDF как рендеринг HTML. Вы пишете HTML и CSS, и DomPDF конвертирует их в PDF. Это удобно, но ограничивает вас тем, что может выразить CSS, без доступа к нативным функциям PDF — цифровым подписям, шифрованию или соответствию PDF/A.
TCPDF-Next предлагает два подхода:
| Подход | Описание | Лучше для |
|---|---|---|
| Core API | Прямое построение PDF через PHP-методы | Точные макеты, формы, графика, подписи |
| Artisan HTML Renderer | Рендерер HTML/CSS на основе DOM (HtmlRenderer) | Контент с большим количеством HTML, миграция с DomPDF |
Для большинства миграций с DomPDF используйте Artisan HTML Renderer — он принимает ваши существующие HTML-шаблоны с минимальными изменениями.
Маппинг API
| DomPDF | TCPDF-Next | Примечания |
|---|---|---|
new Dompdf($options) | PdfDocument::create()->build() | Fluent builder |
$dompdf->loadHtml($html) | $renderer->writeHtml($html) | Тот же HTML работает |
$dompdf->loadHtmlFile($url) | $renderer->writeHtmlFile($path) | По умолчанию только локальные файлы |
$dompdf->setPaper('A4', 'portrait') | ->setPageFormat(PageFormat::A4) | На основе Enum |
$dompdf->render() | Автоматически при save() / toString() | Нет явного шага рендеринга |
$dompdf->output() | $pdf->toString() | Возвращает бинарную строку |
$dompdf->stream('file.pdf') | Хелперы ответов фреймворка | См. примеры ниже |
$options->set('defaultFont', ...) | $renderer->setDefaultFont(...) | |
$options->set('isRemoteEnabled', true) | ResourcePolicy::allowDomain(...) | Явный allowlist |
$options->set('chroot', $dir) | ResourcePolicy::allowLocalDirectory(...) | Более детальный контроль |
Базовый пример миграции
DomPDF (до):
use Dompdf\Dompdf;
use Dompdf\Options;
$options = new Options();
$options->set('defaultFont', 'Helvetica');
$options->set('isRemoteEnabled', true);
$dompdf = new Dompdf($options);
$dompdf->loadHtml($html);
$dompdf->setPaper('A4', 'portrait');
$dompdf->render();
file_put_contents('output.pdf', $dompdf->output());TCPDF-Next (после):
use YeeeFang\TcpdfNext\Document\PdfDocument;
use YeeeFang\TcpdfNext\Document\PageFormat;
use YeeeFang\TcpdfNext\Html\HtmlRenderer;
$pdf = PdfDocument::create()
->setPageFormat(PageFormat::A4)
->build();
$renderer = new HtmlRenderer($pdf);
$renderer->setDefaultFont('Helvetica', size: 12);
$renderer->writeHtml($html);
$pdf->save('output.pdf');Сравнение поддержки CSS
| Возможность CSS | DomPDF | TCPDF-Next |
|---|---|---|
| Box model (margin, padding, border) | Да | Да |
| Floats | Частично | Частично |
| Flexbox | Нет | Нет |
| Grid | Нет | Нет |
position: absolute/relative | Частично | Да |
@font-face | Да | Да |
page-break-before/after | Да | Да |
background-image | Частично | Да |
border-radius | Нет | Да |
opacity | Да | Да |
CSS-переменные (--custom) | Нет | Нет |
| Media queries | Нет | Только @media print |
table layout | Да | Да (улучшено) |
TIP
HTML-рендерер TCPDF-Next поддерживает большинство свойств CSS 2.1 и некоторые свойства CSS 3. Flexbox и Grid не поддерживаются — используйте таблицы для сложных макетов. Если вы столкнётесь с различиями в рендеринге CSS, проверьте документацию HTML Renderer.
Когда использовать Core vs Artisan
| Сценарий | Рекомендуемый подход |
|---|---|
| Миграция существующих HTML-шаблонов | Artisan HTML Renderer |
| Пиксельно-точные макеты (счета, сертификаты) | Core API |
| Требуются цифровые подписи | Core API (подписание работает с обоими, но Core даёт больше контроля) |
| Соответствие PDF/A | Любой (оба поддерживают PDF/A-4) |
| Штрих-коды / QR-коды | Core API (нативный векторный рендеринг) |
| Формы с заполняемыми полями | Core API |
| Простые отчёты из HTML | Artisan HTML Renderer |
Сравнение производительности
| Метрика | DomPDF | TCPDF-Next | Улучшение |
|---|---|---|---|
| Простой 1-страничный PDF | 62,1 мс | 8,2 мс | В 7,6x быстрее |
| 20-страничный отчёт | 891 мс | 187 мс | В 4,8x быстрее |
| Пиковая память (1 стр.) | 22,1 МБ | 4,2 МБ | В 5,3x меньше |
| Пиковая память (20 стр.) | 89,7 МБ | 12,4 МБ | В 7,2x меньше |
| Размер выходного файла (1 стр.) | 31,8 КБ | 12,4 КБ | В 2,6x меньше |
Подробную методологию и дополнительные тест-кейсы смотрите в Бенчмарках производительности.
Новые возможности после миграции
Возможности TCPDF-Next, которые DomPDF не поддерживает:
- Цифровые подписи — PAdES B-B до B-LTA с поддержкой аппаратных модулей безопасности.
- Шифрование AES-256 — Защита документов на основе пароля и сертификата.
- PDF/A-4 — Полное архивное соответствие (ISO 19005-4).
- Tagged PDF / PDF/UA — Доступность для программ чтения с экрана.
- Нативные штрих-коды — QR, Data Matrix, Code 128, EAN и другие как векторная графика.
- Поля форм — Заполняемые текстовые поля, чекбоксы, выпадающие списки.
- Потоки перекрёстных ссылок — Меньший размер файлов с современной структурой PDF.
Дополнительные материалы
- Таблица маппинга API — Детальный маппинг методов
- Бенчмарки — Полное сравнение производительности
- Обзор безопасности — Улучшения безопасности по сравнению с DomPDF
- Справочник API — Полная документация API TCPDF-Next