Bilder, Tabellen und Listen

Text allein ergibt selten ein fertiges Dokument. In diesem Tutorial fügen Sie drei alltägliche Bausteine hinzu: ein Bild, eine Tabelle und eine Aufzählungsliste. Sie schreiben zwei kleine Skripte, und jedes davon erzeugt eine echte PDF-Datei (Portable Document Format), die Sie sofort öffnen können.

Was Sie erstellen

01-image.php — eine einseitige PDF-Datei mit einer Überschrift und einem bernsteinfarbenen quadratischen Bild, das an einer exakten Stelle auf der Seite platziert ist.
02-table-and-lists.php — eine einseitige PDF-Datei mit einer kleinen Tabelle von Büchern und einer Aufzählungsliste darunter.

Beide Skripte sind vollständige Programme. Verwenden Sie weiterhin den Projektordner aus dem ersten Tutorial und speichern Sie jedes Skript neben composer.json.

Schritt 1: Ein Bild auf der Seite platzieren

Dieses Skript trägt sein eigenes Bild in sich. Ein winziges PNG-Bild (Portable Network Graphics) von 8 x 8 Pixeln reist als Base64-Zeichenkette im Skript mit. Base64 ist eine Klartextschreibweise von Binärdaten, sodass sie in Quellcode stehen kann. In einem echten Projekt würden Sie diesen Teil überspringen, weil Ihre Bilddatei bereits auf der Festplatte vorliegt.

Speichern Sie dies als 01-image.php und führen Sie es mit php 01-image.php aus:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// A tiny 8 x 8 pixel amber PNG, stored as text inside this script.
// In a real project the image file already exists on disk, so you
// would skip this block and point image() at your own file.
$pngBase64 = 'iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAEUlEQVR42mP4Oo8bK2IYWhIAq6BngWh/dt4AAAAASUVORK5CYII=';

@mkdir(__DIR__ . '/out');

$pngPath = __DIR__ . '/out/amber-square.png';
$pngBytes = base64_decode($pngBase64, true);
if ($pngBytes === false) {
    fwrite(STDERR, "The embedded image data is damaged.\n");
    exit(1);
}
file_put_contents($pngPath, $pngBytes);

$document = Document::createStandalone();
$document->setTitle('Tutorial: images');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 26, 'A picture inside a PDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 18, 'The amber square below comes from a tiny PNG file.', newLine: true);

// Place the image 72 points (one inch) from the left edge and
// 160 points down from the top, printed as a 96 x 96 point square.
$document->image($pngPath, x: 72, y: 160, width: 96, height: 96);

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

echo "Wrote out/image.pdf\n";

Auf dem Bildschirm sollten Sie Wrote out/image.pdf sehen. Öffnen Sie out/image.pdf, und Sie finden die Überschrift, eine Textzeile und ein bernsteinfarbenes Quadrat.

Was gerade geschehen ist

Das Skript decodiert zunächst die Base64-Zeichenkette zurück in Bildbytes und schreibt sie nach out/amber-square.png. Das ist nur der Kniff, der dieses Tutorial in sich geschlossen hält. Die eigentliche Lektion beginnt beim Aufruf von image(), der jede vorhandene PNG- oder JPEG-Datei (Joint Photographic Experts Group) auf dieselbe Weise liest.
@mkdir(__DIR__ . '/out') erstellt den Ausgabeordner. Das Zeichen @ unterdrückt die harmlose Warnung, die Sie erhalten würden, wenn der Ordner bereits existiert, sodass sich das Skript zweimal hintereinander ausführen lässt.
image() erwartet einen Dateipfad sowie eine Position und eine Druckgröße. Positionen und Größen werden in Punkten gemessen, und 72 Punkte entsprechen einem Zoll. Der Seitenursprung ist die obere linke Ecke, y: 160 bedeutet also 160 Punkte von oben.
Pixel und Punkte sind verschiedene Dinge. Das Bild ist nur 8 x 8 Pixel groß, aber width: 96, height: 96 druckt es als Quadrat mit einer Kantenlänge von ein und ein Drittel Zoll. Sie bestimmen die Druckgröße, nicht die Pixelanzahl.
image() platziert das Bild genau an der Stelle, die Sie angeben. Es verschiebt nicht die Schreibposition, die cell() verwendet. Wenn Sie zuerst den Text schreiben und danach die Bilder platzieren, kollidieren beide nicht miteinander.
NextPDF liest das Bild ausschließlich aus einer lokalen Datei, niemals von einer Webadresse. Es prüft, ob die Datei ein echtes, unterstütztes Bild ist, bevor es sie einbettet. Dieser Schutz hilft Ihnen, wenn Dateinamen von Benutzern stammen.

Schritt 2: Eine Tabelle und eine Aufzählungsliste hinzufügen

Tabellen und Listen sind strukturierte Inhalte. Der schnellste Weg, Struktur zu beschreiben, ist HTML (Hypertext Markup Language), dieselbe Auszeichnungssprache, die Webseiten verwenden. NextPDF rendert eine unterstützte Teilmenge von HTML direkt auf die PDF-Seite. Dabei ist kein Browser beteiligt.

Speichern Sie dies als 02-table-and-lists.php und führen Sie es mit php 02-table-and-lists.php aus:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Tutorial: tables and lists');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 26, 'A reading list, two ways', newLine: true);
$document->ln(8);

$html = <<<'HTML'
<h2>The books as a table</h2>
<table border="1" cellpadding="6" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 50%;">Title</th>
            <th style="width: 20%; text-align: center;">Year</th>
            <th style="width: 30%; text-align: right;">Pages</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>The Paper Office</td>
            <td style="text-align: center;">2019</td>
            <td style="text-align: right;">312</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>Ink and Pixels</td>
            <td style="text-align: center;">2023</td>
            <td style="text-align: right;">208</td>
        </tr>
    </tbody>
</table>

<h2>Why these two books</h2>
<ul>
    <li>Short chapters that fit into a lunch break</li>
    <li>Worked examples on every page</li>
    <li>No jargon without an explanation</li>
</ul>
HTML;

$document->writeHtml($html);

$document->save(__DIR__ . '/out/table-and-lists.pdf');

echo "Wrote out/table-and-lists.pdf\n";

Sie sollten Wrote out/table-and-lists.pdf sehen. Die PDF-Datei enthält eine Überschrift, eine dreispaltige Tabelle mit einer dunklen Kopfzeile und eine Aufzählungsliste.

Was gerade geschehen ist

Das Skript kombiniert beide Schreibweisen auf einer Seite. cell() gibt die große Überschrift an der aktuellen Schreibposition aus. writeHtml() lässt anschließend die Tabelle und die Liste darunter auf der Seite nach unten fließen.
ln(8) fügt einen kleinen vertikalen Abstand von acht Punkten Höhe zwischen der Überschrift und dem HTML-Inhalt ein. Ohne ihn würden beide eng beieinanderstehen.
Die Tabelle verwendet gewöhnliche Tabellenauszeichnung: <thead> für die Kopfzeile, <tbody> für die Datenzeilen, <th> für Kopfzellen und <td> für Datenzellen. border="1" zeichnet die Gitterlinien, und cellpadding="6" schafft etwas Luft innerhalb jeder Zelle.
Spaltenbreiten sind Prozentangaben wie width: 50%. Sie teilen die volle Breite der Tabelle auf, sodass das Layout eine Änderung der Seitengröße übersteht. Das Rezept HTML-Tabelle gestalten behandelt Kopfzeilen, Fußzeilen und Spaltendimensionierung ausführlich.
Die style-Attribute verwenden CSS-Deklarationen (Cascading Style Sheets), die Gestaltungssprache des Webs. Farben, Ausrichtung und Breiten funktionieren wie hier gezeigt. Bevor Sie sich auf andere Eigenschaften verlassen, prüfen Sie die CSS-Unterstützungsmatrix.
Die Aufzählungsliste ist einfach <ul> mit einem <li> pro Eintrag. NextPDF zeichnet die Aufzählungszeichen und die Einrückung für Sie.

Falls etwas schiefgegangen ist

Ein Fehler mit ImageProcessingException bedeutet, dass die Bilddatei nicht gelesen oder decodiert werden konnte. Prüfen Sie den Pfad und vergewissern Sie sich, dass die Datei ein unterstütztes Format wie PNG oder JPEG ist.
Ein Fehler mit PageLayoutException bedeutet, dass eine Position oder Größe abgelehnt wurde. Breite und Höhe müssen größer als null sein, und der Pfad muss auf eine lokale Datei verweisen, nicht auf eine Webadresse.
Beide Fehler werden in der Referenz zu Engine-Fehlern beschrieben.
Wenn die Tabelle seltsam gerendert wird, prüfen Sie zuerst die Auszeichnung. Jede <tr>-Zeile und jede <td>-Zelle benötigt ihr schließendes Tag.
Für alles Weitere beginnen Sie beim Leitfaden zur Fehlerbehebung.

Weiter

Ihre Seiten können nun Bilder, Tabellen und Listen tragen. Im nächsten Tutorial lassen Sie ein Dokument über eine Seite hinauswachsen und halten es mit Kopfzeilen, Fußzeilen und Seitenzahlen ordentlich. Für tiefere Einblicke in die heutigen Themen behandelt das Rezept Bilder in ein Dokument einbetten Bildformate und Regeln zur Größenanpassung.