HTML в PDF: простой путь

До сих пор в этом цикле вы создавали страницы по одному вызову за раз. Многие документы быстрее описать в виде разметки — текстового формата на основе тегов, который используется для веб-страниц. В этом учебном руководстве вы передаёте NextPDF фрагмент Hypertext Markup Language (HTML), и движок сам рисует страницу за вас.

Что вы создадите

Одностраничный отчёт, отрисованный из единственной строки HTML. В нём есть цветной заголовок, короткий абзац и таблица со строкой итогов. Оформление задаётся с помощью Cascading Style Sheets (CSS) — языка правил, который управляет тем, как выглядит разметка. В предыдущих учебных руководствах вы использовали гибкий Application Programming Interface (API) — цепочку вызовов методов. Здесь вы вместо этого описываете макет в разметке, и тот же самый движок его отрисовывает.

Шаг 1: Отрисовка стилизованного отчёта из HTML

Создайте файл с именем 01-html.php в папке проекта, рядом с vendor. Вставьте в него этот полный скрипт:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Monthly reading report');
$document->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Monthly reading report</h1>

<p>This report was rendered from <strong>HTML</strong> with inline
<em>CSS</em>. The table below lists two books and their page counts.</p>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 55%;">Title</th>
            <th style="width: 20%; text-align: center;">Format</th>
            <th style="width: 25%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Trail</td>
            <td style="text-align: center;">Hardcover</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Bytes</td>
            <td style="text-align: center;">Paperback</td>
            <td style="text-align: right;">248</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="font-weight: bold;">
            <td colspan="2" style="text-align: right;">Total pages:</td>
            <td style="text-align: right;">560</td>
        </tr>
    </tfoot>
</table>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/reading-report.pdf');

echo "Wrote out/reading-report.pdf\n";

Запустите скрипт из папки проекта:

php 01-html.php

Вы должны увидеть одну строку вывода:

Wrote out/reading-report.pdf

Откройте out/reading-report.pdf в любой программе для просмотра Portable Document Format (PDF). Заголовок тёмно-синий, а строка заголовка таблицы залита тем же цветом.

Что только что произошло

@mkdir(__DIR__ . '/out'); создаёт папку для вывода. Знак @ скрывает предупреждение, если папка уже существует, поэтому повторные запуски проходят без лишних сообщений.
Document::createStandalone(), setTitle() и addPage() работают точно так же, как в предыдущих учебных руководствах. Переход на разметку ничего не меняет в настройке документа.
writeHtml() читает вашу строку один раз, сверху вниз, и рисует каждый элемент в текущей позиции. Заголовки и абзацы становятся стилизованным текстом. Таблица превращается в строки из ячеек с рамками.
Встроенные атрибуты style несут CSS. Движок понимает распространённые свойства, такие как color, background-color, text-align и width.
Никакой браузер и никакое дополнительное программное обеспечение не задействованы. Конвейер — это обычный PHP внутри движка, поэтому скрипт работает везде, где работает ваша установка Composer.

Движок поддерживает практичное подмножество HTML и CSS, а не всё, что принимает браузер. Всё, что выходит за пределы этого подмножества, тихо пропускается, а не вызывает ошибку. Матрица поддержки CSS точно фиксирует, что именно охвачено. Более подробный разбор этого конвейера см. в Отрисовка HTML в страницу PDF.

Когда использовать HTML, а когда — гибкий API

Оба пути работают на одном и том же движке, поэтому выбирайте тот, который подходит документу.

Выбирайте writeHtml(), когда документ читается как веб-страница: заголовки, абзацы, списки и таблицы. Разметку быстрее писать, и коллегам её проще править.
Выбирайте гибкий API, когда вам нужно точное размещение, например фиксированные позиции или ячейки с точно заданными размерами. Разметка даёт вам поток; гибкие вызовы дают вам контроль.
Прежде чем полагаться на свойство, проверьте матрицу поддержки CSS. Если стиль не охвачен, соберите эту часть с помощью гибких вызовов.

Граница безопасности

Реальный HTML часто приходит из-за пределов вашего кода, например из формы или базы данных. Относитесь к нему как к недоверенному вводу и проверяйте или очищайте его перед отрисовкой. По умолчанию встроенный конвейер не выполняет никаких скриптов и не загружает удалённые ресурсы. Благодаря этому обработчик остаётся консервативным, даже когда сама разметка таковой не является. Если вам нужны возможности отрисовки уровня браузера, см. Выберите подходящий путь.

Если что-то пошло не так

Failed to open stream: No such file or directory обычно означает, что скрипт не может найти vendor/autoload.php. Запускайте его из папки, где вы выполняли Composer.
Отсутствующий стиль — это обычно свойство за пределами поддерживаемого подмножества. Движок пропускает то, что не поддерживает, вместо того чтобы завершиться с ошибкой. Сравните вашу разметку с матрицей поддержки CSS.
Исключение во время отрисовки называет точную проблему. Найдите его в справочнике ошибки отрисовки и ввода-вывода.

В остальных случаях начните с руководства по устранению неполадок.

Дальше

Теперь вы можете создавать документы как вызов за вызовом, так и из разметки. Завершите этот цикл разделом Куда двигаться дальше. Он показывает, где искать сборник рецептов, справочник и руководства, которые вы будете использовать после этого цикла.