HTML do PDF, prosta ścieżka

Dotychczas na tej ścieżce budowałeś strony pojedynczo, wywołanie po wywołaniu. Wiele dokumentów da się szybciej opisać za pomocą znaczników — tekstowego formatu opartego na tagach, używanego na stronach internetowych. W tym samouczku przekazujesz do NextPDF kod Hypertext Markup Language (HTML), a silnik rysuje stronę za Ciebie.

Co zbudujesz

Jednostronicowy raport wyrenderowany z pojedynczego łańcucha HTML. Zawiera kolorowy nagłówek, krótki akapit oraz tabelę z wierszem sum. Stylizujesz go za pomocą Cascading Style Sheets (CSS) — języka reguł, który określa wygląd znaczników. We wcześniejszych samouczkach korzystałeś z płynnego Application Programming Interface (API), czyli łańcuchowych wywołań metod. Tutaj zamiast tego opisujesz układ za pomocą znaczników, a ten sam silnik go renderuje.

Krok 1: Wyrenderuj stylizowany raport z HTML

Utwórz plik o nazwie 01-html.php w folderze projektu, obok vendor. Wklej ten kompletny skrypt:

<?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";

Uruchom skrypt z folderu projektu:

php 01-html.php

Powinieneś zobaczyć jedną linię wyniku:

Wrote out/reading-report.pdf

Otwórz out/reading-report.pdf w dowolnej przeglądarce plików Portable Document Format (PDF). Nagłówek jest ciemnoniebieski, a wiersz nagłówka tabeli jest wypełniony tym samym kolorem.

Co się właśnie wydarzyło

@mkdir(__DIR__ . '/out'); tworzy folder wyjściowy. Znak @ ukrywa ostrzeżenie, gdy folder już istnieje, dzięki czemu kolejne uruchomienia pozostają ciche.
Document::createStandalone(), setTitle() i addPage() działają dokładnie tak jak we wcześniejszych samouczkach. Przejście na znaczniki niczego nie zmienia w konfiguracji dokumentu.
writeHtml() odczytuje łańcuch jeden raz, od góry do dołu, i rysuje każdy element w bieżącej pozycji. Nagłówki i akapity stają się stylizowanym tekstem. Tabela staje się zmierzonymi wierszami komórek z obramowaniem.
Wbudowane atrybuty style przenoszą CSS. Silnik rozumie typowe właściwości, takie jak color, background-color, text-align i width.
Nie bierze w tym udziału żadna przeglądarka ani dodatkowe oprogramowanie. Potok to zwykły PHP wewnątrz silnika, więc skrypt działa wszędzie tam, gdzie działa instalacja Composer.

Silnik obsługuje praktyczny podzbiór HTML i CSS, a nie wszystko, co akceptuje przeglądarka. Wszystko, co wykracza poza ten podzbiór, jest po cichu pomijane, zamiast zgłaszać błąd. Macierz obsługi CSS dokładnie dokumentuje, co jest objęte wsparciem. Aby dokładniej poznać ten potok, zobacz Renderowanie HTML na stronę PDF.

Kiedy używać HTML, a kiedy płynnego API

Obie drogi działają na tym samym silniku, więc wybierz tę, która pasuje do dokumentu.

Wybierz writeHtml(), gdy dokument przypomina stronę internetową: nagłówki, akapity, listy i tabele. Znaczniki szybciej się pisze i łatwiej je edytować członkom zespołu.
Wybierz płynne API, gdy potrzebujesz dokładnego rozmieszczenia, na przykład stałych pozycji lub precyzyjnie zmierzonych komórek. Znaczniki dają przepływ; płynne wywołania dają kontrolę.
Sprawdź macierz obsługi CSS, zanim zaczniesz polegać na danej właściwości. Gdy styl nie jest objęty wsparciem, zbuduj tę część za pomocą płynnych wywołań.

Granica bezpieczeństwa

W praktyce HTML często pochodzi spoza Twojego kodu, na przykład z formularza lub bazy danych. Traktuj go jako niezaufane dane wejściowe i zwaliduj lub oczyść przed renderowaniem. Domyślnie wbudowany potok nie uruchamia żadnych skryptów ani nie pobiera zdalnych zasobów. Ten domyślny tryb sprawia, że renderer pozostaje konserwatywny, nawet gdy znaczniki takie nie są. Jeśli potrzebujesz opcji renderowania na poziomie przeglądarki, zobacz Wybierz właściwą ścieżkę.

Jeśli coś poszło nie tak

Failed to open stream: No such file or directory zwykle oznacza, że skrypt nie może znaleźć vendor/autoload.php. Uruchom go z folderu, w którym uruchomiłeś Composer.
Brakujący styl to zwykle właściwość spoza obsługiwanego podzbioru. Silnik pomija to, czego nie obsługuje, zamiast zgłaszać błąd. Porównaj znaczniki z macierzą obsługi CSS.
Wyjątek podczas renderowania wskazuje dokładny problem. Sprawdź go w dokumentacji błędów renderowania oraz wejścia/wyjścia.

W przypadku wszystkiego innego zacznij od przewodnika rozwiązywania problemów.

Dalej

Umiesz już budować dokumenty wywołanie po wywołaniu oraz ze znaczników. Zakończ tę ścieżkę stroną Dokąd dalej. Wskazuje ona Receptariusz, dokumentację referencyjną oraz przewodniki, z których skorzystasz po tej ścieżce.