HTML zu PDF, der einfache Weg

Bisher haben Sie in dieser Reihe Seiten Aufruf für Aufruf aufgebaut. Viele Dokumente lassen sich schneller mit Markup beschreiben, dem tag-basierten Textformat für Webseiten. In diesem Tutorial übergeben Sie NextPDF etwas Hypertext Markup Language (HTML), und die Engine zeichnet die Seite für Sie.

Was Sie erstellen

Ein einseitiger Bericht, gerendert aus einem einzigen HTML-String. Er enthält eine farbige Überschrift, einen kurzen Absatz und eine Tabelle mit einer Summenzeile. Sie gestalten ihn mit Cascading Style Sheets (CSS), der Regelsprache, die das Aussehen von Markup steuert. In den vorherigen Tutorials haben Sie die fluente Application Programming Interface (API) verwendet, die verketteten Methodenaufrufe. Hier beschreiben Sie das Layout stattdessen als Markup, und dieselbe Engine rendert es.

Schritt 1: Einen gestalteten Bericht aus HTML rendern

Erstellen Sie im Projektordner neben vendor eine Datei mit dem Namen 01-html.php. Fügen Sie dieses vollständige Skript ein:

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

Führen Sie das Skript aus dem Projektordner aus:

php 01-html.php

Sie sollten eine Zeile Ausgabe sehen:

Wrote out/reading-report.pdf

Öffnen Sie out/reading-report.pdf in einem beliebigen Viewer für das Portable Document Format (PDF). Die Überschrift ist dunkelblau, und die Kopfzeile der Tabelle ist mit derselben Farbe gefüllt.

Was gerade passiert ist

@mkdir(__DIR__ . '/out'); erstellt den Ausgabeordner. Das @-Zeichen unterdrückt die Warnung, wenn der Ordner bereits vorhanden ist, sodass wiederholte Durchläufe still bleiben.
Document::createStandalone(), setTitle() und addPage() funktionieren genau wie in den vorherigen Tutorials. Der Wechsel zu Markup ändert nichts an der Dokumenteinrichtung.
writeHtml() liest Ihren String einmal von oben nach unten und zeichnet jedes Element an der aktuellen Position. Überschriften und Absätze werden zu gestaltetem Text. Die Tabelle wird zu ausgemessenen Zeilen aus umrandeten Zellen.
Die Inline-style-Attribute enthalten das CSS. Die Engine versteht gängige Eigenschaften wie color, background-color, text-align und width.
Kein Browser und keine zusätzliche Software sind beteiligt. Die Pipeline ist reines PHP innerhalb der Engine, sodass das Skript überall dort läuft, wo Ihre Composer-Installation läuft.

Die Engine unterstützt eine praxistaugliche Teilmenge von HTML und CSS, nicht alles, was ein Browser akzeptiert. Alles außerhalb dieser Teilmenge wird stillschweigend übersprungen, statt einen Fehler auszulösen. Die CSS-Support-Matrix hält genau fest, was abgedeckt ist. Für einen ausführlicheren Durchgang durch diese Pipeline siehe HTML als PDF-Seiteninhalt rendern.

Wann HTML und wann die fluente API zu verwenden ist

Beide Wege laufen auf derselben Engine, wählen Sie also den, der zum Dokument passt.

Wählen Sie writeHtml(), wenn sich das Dokument wie eine Webseite liest: Überschriften, Absätze, Listen und Tabellen. Markup ist schneller zu schreiben und für Teammitglieder leichter zu bearbeiten.
Wählen Sie die fluente API, wenn Sie eine exakte Platzierung benötigen, etwa feste Positionen oder präzise ausgemessene Zellen. Markup gibt Ihnen den Fluss; die fluenten Aufrufe geben Ihnen die Kontrolle.
Prüfen Sie die CSS-Support-Matrix, bevor Sie sich auf eine Eigenschaft verlassen. Wenn ein Stil nicht abgedeckt ist, bauen Sie diesen Teil stattdessen mit fluenten Aufrufen.

Die Sicherheitsgrenze

Echtes HTML stammt oft von außerhalb Ihres Codes, zum Beispiel aus einem Formular oder einer Datenbank. Behandeln Sie es als nicht vertrauenswürdige Eingabe und validieren oder bereinigen Sie es vor dem Rendern. Standardmäßig führt die eingebaute Pipeline keine Skripte aus und ruft keine entfernten Ressourcen ab. Diese Voreinstellung hält den Renderer konservativ, selbst wenn das Markup es nicht ist. Wenn Sie Rendering-Optionen auf Browser-Niveau benötigen, siehe Wählen Sie Ihren Weg.

Wenn etwas schiefgelaufen ist

Failed to open stream: No such file or directory bedeutet in der Regel, dass das Skript vendor/autoload.php nicht finden kann. Führen Sie es aus dem Ordner aus, in dem Sie Composer ausgeführt haben.
Ein fehlender Stil ist meist eine Eigenschaft außerhalb der unterstützten Teilmenge. Die Engine überspringt, was sie nicht unterstützt, statt zu scheitern. Vergleichen Sie Ihr Markup mit der CSS-Support-Matrix.
Eine Ausnahme während des Renderns benennt das genaue Problem. Schlagen Sie es in der Referenz Rendering- und I/O-Fehler nach.

Für alles Weitere beginnen Sie mit dem Leitfaden zur Fehlerbehebung.

Als Nächstes

Sie können nun Dokumente Aufruf für Aufruf und aus Markup erstellen. Schließen Sie die Reihe mit Wohin als Nächstes ab. Dort wird auf das Cookbook, die Referenz und die Leitfäden verwiesen, die Sie nach dieser Reihe verwenden werden.