Пакет Artisan

Artisan · LGPL-3.0

Пакет Artisan (yeeefang/tcpdf-next-artisan) обеспечивает попиксельное преобразование HTML-в-PDF на основе Chrome DevTools Protocol (CDP). Он рендерит HTML с полной поддержкой CSS3 -- включая Flexbox, Grid, веб-шрифты, медиа-запросы и анимации, зафиксированные на момент рендеринга.

Когда использовать Artisan

Сценарий	Рекомендация
Генерация PDF из HTML/CSS шаблонов	Artisan
Программное построение PDF (ячейки, рисование)	Core
HTML-письма в PDF-архив	Artisan
Счёт-фактура из структурированных данных	Core или Artisan
Сложные CSS-макеты (Grid, Flexbox)	Artisan
Подписанные/зашифрованные PDF	Core

Как это работает

Artisan запускает экземпляр Chrome в headless-режиме через Chrome DevTools Protocol, загружает ваш HTML-контент в страницу браузера и использует встроенную функцию Chrome для печати в PDF. Это означает, что каждая CSS-функция, поддерживаемая Chrome, доступна для ваших PDF -- больше не нужно бороться с ограниченными CSS-парсерами.

HTML/CSS --> ChromeBridge --> Chrome CDP --> PDF binary --> save / stream

Установка

bash

composer require yeeefang/tcpdf-next-artisan

Требования:

PHP 8.2+
chrome-php/chrome ^1.15 (устанавливается автоматически)
Браузер Chrome или Chromium, установленный на хосте

bash

# Ubuntu/Debian
apt-get install -y chromium-browser

# macOS
brew install --cask chromium

# Windows (Chocolatey)
choco install googlechrome

# Set a custom path via environment variable
export CHROME_PATH=/usr/bin/google-chrome

Быстрый старт

php

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create();

$renderer
    ->loadHtml('<h1>Hello, World!</h1><p>Rendered with Chrome CDP.</p>')
    ->save('/output/hello.pdf');

Из URL

php

HtmlRenderer::create()
    ->loadUrl('https://example.com/report')
    ->save('/output/report.pdf');

Из файла

php

HtmlRenderer::create()
    ->loadFile('/templates/invoice.html')
    ->save('/output/invoice.pdf');

Содержимое пакета

Класс	Назначение
`HtmlRenderer`	Главная точка входа -- загрузка HTML, настройка, рендеринг
`ChromeBridge`	Коммуникация через Chrome DevTools Protocol
`RenderOptions`	Конфигурация рендеринга (поля, масштаб, колонтитулы)
`PageSetup`	Размер страницы и ориентация для рендеринга
`PdfMerger`	Объединение нескольких отрендеренных страниц в один PDF
`StyleInjector`	Внедрение CSS-стилей перед рендерингом
`ScreenshotCapture`	Захват скриншотов страницы (PNG/JPEG)

Иерархия исключений

Исключение	Когда возникает
`RenderException`	Общая ошибка рендеринга
`ChromeNotFoundException`	Бинарный файл Chrome не найден по ожидаемому пути
`TimeoutException`	Загрузка страницы или рендеринг превысили настроенный таймаут

Все исключения находятся в namespace Yeeefang\TcpdfNext\Artisan\Exceptions и наследуют общий базовый класс ArtisanException.

Сравнение с HTML-парсером Core

Пакет Core включает модуль HtmlParser для базового преобразования HTML-в-PDF. Используйте его, когда нужно решение без зависимостей. Используйте Artisan, когда нужна полная точность рендеринга браузера.

Функция	Core HtmlParser	Artisan
Внешняя зависимость	Нет	Chrome/Chromium
CSS Flexbox / Grid	Нет	Да
Веб-шрифты (`@font-face`)	Нет	Да
Медиа-запросы	Нет	Да
Выполнение JavaScript	Нет	Да
CSS-правила `@page`	Нет	Да
Производительность (простые документы)	Быстрее	Медленнее
Производительность (сложный CSS)	Н/Д	Надёжно

HTML Renderer -- Загрузка и рендеринг HTML-контента.
Render Options -- Настройка размера страницы, полей, колонтитулов.
Продвинутые функции -- Объединение PDF, внедрение CSS, скриншоты.
Настройка Docker -- Запуск Artisan в контейнерах.

Пакет Artisan ​

Когда использовать Artisan ​

Как это работает ​

Установка ​

Быстрый старт ​

Из URL ​

Из файла ​

Содержимое пакета ​

Иерархия исключений ​

Сравнение с HTML-парсером Core ​

Далее ​