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

Краткий обзор

Подключите ChromeRendererConfig к документу NextPDF, вызовите writeHtmlChrome() и сохраните файл Portable Document Format (PDF). Chrome отрисует Hypertext Markup Language (HTML). Мост импортирует результат как Form XObject, поэтому текст останется выделяемым.

Концептуальный обзор

writeHtmlChrome() — метод ядра NextPDF Document. Его предоставляет трейт HasTextOutput. Метод проверяет входные данные и определяет средство отрисовки Artisan. Затем он отправляет HTML в Chrome, анализирует возвращённый PDF и встраивает страницу 0 как Form XObject в текущей позиции курсора. Публичная сигнатура — writeHtmlChrome(string $html, ?float $width = null, ?float $height = null): static; проверено по nextpdf/coresrc/Core/Concerns/HasTextOutput.php.

Пример кода — быстрый старт

quickstart.php

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

$doc = Document::createStandalone();
$doc->setChromeRendererConfig($config);
$doc->addPage();

$doc->writeHtmlChrome('
    <div style="display: flex; gap: 20px; font-family: sans-serif;">
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Revenue</h2><p style="font-size: 2em; color: #2563eb;">$124,500</p>
        </div>
        <div style="flex: 1; background: #f0f0f0; padding: 24px;">
            <h2>Orders</h2><p style="font-size: 2em; color: #16a34a;">1,847</p>
        </div>
    </div>
');

$doc->save('/tmp/report.pdf');

Это канонический процесс из README.md пакета. Chrome обрабатывает макет Cascading Style Sheets (CSS) flex. В выводе числа остаются выделяемым текстом, потому что страница встраивается как Form XObject, а не как растровое изображение.

Пользовательский размер страницы

Передайте явные ширину и высоту в точках PDF, чтобы задать фиксированный размер страницы (показан A4):

$doc->writeHtmlChrome($html, width: 595.28, height: 841.89);

Если вы указываете оба значения, Chrome печатает точно в этот размер бумаги. Если вы опускаете высоту (или передаёте null), мост подгоняет страницу под измеренную высоту содержимого и добавляет небольшой запас на перекомпоновку. См. /integrations/artisan/production-usage/: там объясняется, зачем нужен этот запас и когда его следует переопределять.

Что вы получаете

Свойство	Поведение
Текст	Выделяемый и доступный для поиска (векторный текст, не растеризованный)
Каскадные таблицы стилей (Cascading Style Sheets, CSS)	Макет Chrome: flexbox, grid, сложные селекторы, веб-шрифты через значения data Uniform Resource Identifier (URI)
Сеть	Нет запросов подресурсов; удалённые Uniform Resource Locators (URLs) не загружаются (см. /integrations/artisan/security-and-operations/)
Страницы	Импортируется страница 0 вывода Chrome

Граничные случаи и подводные камни

• Пустой HTML ничего не делает. writeHtmlChrome('') возвращает документ без изменений (проверено в HasTextOutput::writeHtmlChrome).
• Страницы ещё нет. Если в документе нет страницы, writeHtmlChrome() добавляет её перед отрисовкой.
• Удалённые ресурсы не загружаются. <img src="https://..."> отображается пустым. Встраивайте ресурсы как URI data:. Это режим сетевой изоляции, а не ошибка. См. /integrations/artisan/security-and-operations/.
• Мост отсутствует. Если nextpdf/artisan не установлен, ядро выбрасывает исключение макета вместо фатальной ошибки.

Производительность

Первый вызов включает время запуска Chrome и компоновки. Последующие вызовы повторно используют работающий процесс Chrome через BrowserPool. Для пакетных задач или долго работающих воркеров ознакомьтесь с рекомендациями по жизненному циклу и ресурсам на странице /integrations/artisan/production-usage/.

Замечания по безопасности

В этом быстром старте используется доверенный HTML, жёстко заданный в коде. Прежде чем передавать в writeHtmlChrome() любой HTML, на который влияет пользователь, прочитайте /integrations/artisan/security-and-operations/. Мост изолирует доступ к сети, но у отрисовки HTML всё же есть поверхность атаки.

Коммерческий контекст

Так создаётся PDF из HTML с помощью моста с открытым исходным кодом. Чтобы встроить в тот же документ соответствующий стандартам файл электронного счёта в формате Extensible Markup Language (XML), в тарифе Premium Pro есть средство встраивания. Путь с открытым исходным кодом не затрагивается, когда Premium отсутствует.

См. также

• /integrations/artisan/install/ — Установка
• /integrations/artisan/configuration/ — Настройка
• /integrations/artisan/production-usage/ — Использование в продакшене
• /integrations/artisan/troubleshooting/ — Устранение неполадок
• /integrations/artisan/security-and-operations/ — Безопасность и эксплуатация