NextPDF einrichten und Ihr erstes PDF rendern

NextPDF ist eine PHP-Bibliothek, die PDF-Dateien (Portable Document Format) erstellt. In diesem Tutorial installieren Sie sie in einem leeren Ordner und rendern Ihr erstes einseitiges Dokument. Sie benötigen ein Terminal und etwa zehn Minuten.

Was Sie erstellen werden

Sie erstellen ein winziges Projekt, das ein einziges Skript enthält, 01-hello.php. Das Skript rendert eine einzelne Seite mit einer fett gesetzten Titelzeile und einem Absatz. Es speichert das Ergebnis als out/hello.pdf. Nebenbei lernen Sie zwei Befehle kennen, die bestätigen, dass Ihre Installation intakt ist.

Diese Seite zeigt einen Installationsweg: ein leerer Ordner plus das Engine-Paket. Es gibt weitere Wege, etwa Framework-Adapter, browserbasierte Renderer und den Python-Client. Diese finden Sie unter Installation und Wählen Sie Ihren Weg. Heute benötigen Sie sie nicht.

Schritt 1: Ein Projekt anlegen und NextPDF installieren

Composer ist der Paketmanager für PHP. Er lädt Bibliotheken in Ihr Projekt und generiert einen Autoloader. Ein Autoloader ist eine kleine PHP-Datei, die die Bibliotheksklassen für Sie findet, sodass Sie niemals lange Listen von Includes schreiben.

Öffnen Sie ein Terminal und führen Sie diese drei Befehle aus:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer gibt den Fortschritt aus, während er die Pakete auflöst und herunterlädt. Die genauen Zeilen hängen von Ihrer Composer-Version und Ihrem lokalen Cache ab. Eine erfolgreiche Installation endet ohne Fehlermeldung und sieht ungefähr so aus:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

Was gerade passiert ist

Composer hat drei Dinge in Ihrem Ordner erstellt. composer.json hält fest, dass Ihr Projekt von der Engine abhängt. composer.lock fixiert die exakte Version, die installiert wurde, sodass eine spätere Installation denselben Code auflöst. Der Ordner vendor/ enthält die heruntergeladenen Pakete, einschließlich vendor/autoload.php. Ihr Skript lädt diese eine Datei, und jede Engine-Klasse wird verfügbar.

Composer hat während der Installation außerdem Ihre PHP-Einrichtung geprüft. Die Engine deklariert die PHP-Erweiterungen, die sie benötigt. Erweiterungen sind optionale Module, die in PHP eingebaut sind. Fehlt eine, stoppt Composer und benennt sie, statt Sie mit einer defekten Installation zurückzulassen.

Schritt 2: Ihr erstes PDF rendern

Erstellen Sie eine Datei namens 01-hello.php neben composer.json. Fügen Sie dieses vollständige Programm ein:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

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

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

Führen Sie es aus:

php 01-hello.php

Sie sollten genau eine Zeile sehen:

Wrote out/hello.pdf

Öffnen Sie out/hello.pdf in einem beliebigen PDF-Betrachter. Sie sehen die fett gesetzte Titelzeile mit dem Absatz darunter, und die meisten Betrachter zeigen “Hello from NextPDF” in ihrer Fenstertitelleiste.

Was gerade passiert ist

Gehen Sie das Skript von oben nach unten durch:

require lädt den Composer-Autoloader, sodass die Klasse Document aufgelöst wird.
@mkdir erstellt den Ordner out/. Das vorangestellte @ unterdrückt die Warnung, wenn der Ordner bereits existiert, sodass Sie es erneut ausführen können.
Document::createStandalone() liefert ein neues Dokument zurück. Es ist genau für kurze Kommandozeilen-Skripte wie dieses gemacht.
setTitle() setzt den Dokumenttitel, den Betrachter in der Fenstertitelleiste anzeigen.
addPage() fügt eine leere Seite hinzu und platziert den Cursor oben links.
setFont() wählt eine Schriftfamilie, einen Stil und eine Größe in Punkt. Punkt ist die Standardeinheit für Schriftgrößen im Druck. 'B' bedeutet fett und '' bedeutet normal. Die Familie namens helvetica ist eingebaut, sodass Sie keine Schriftdateien benötigen.
cell() schreibt eine Textzeile an der Cursorposition. Eine Breite von 0 bedeutet “bis zum rechten Rand strecken”. newLine: true bewegt den Cursor anschließend nach unten, wie das Drücken der Eingabetaste.
save() baut das fertige PDF und schreibt es auf die Festplatte.

Ein Dokument erzeugt eine Datei. Wenn Sie ein zweites PDF benötigen, erstellen Sie ein neues Dokument, statt das alte wiederzuverwenden.

Schritt 3: Ihre Einrichtung überprüfen

Zwei schnelle Prüfungen bestätigen, dass diese Installation über ein einzelnes Skript hinaus funktionieren wird.

Listen Sie zunächst die Erweiterungen auf, die Ihr PHP mitbringt:

php -m

Durchsuchen Sie die Liste nach curl, gd, intl, mbstring, openssl und zlib. Die Engine ist auf diese sechs angewiesen. Composer hat sie in Schritt 1 bereits geprüft, sodass sie alle erscheinen sollten.

Führen Sie zweitens den eigenen Funktionstest der Engine aus:

vendor/bin/nextpdf doctor

Unter Windows rufen Sie stattdessen vendor\bin\nextpdf doctor auf. Der Befehl prüft Ihre PHP-Version, die Erweiterungen, den temporären Ordner und die Konfiguration. Jede Prüfung gibt [OK], [WARN] oder [FAIL] aus, gefolgt von einem Gesamturteil.

Was gerade passiert ist

Lesen Sie zuerst den Block Extensions. Sechs [OK]-Zeilen mit den Namen curl, gd, intl, mbstring, openssl und zlib bedeuten, dass Ihre Installation für jedes folgende Tutorial bereit ist.

Der Bericht listet außerdem die Fähigkeiten der Engine auf. Bei der kostenlosen Core-Installation geben die Fähigkeiten, die zu den kommerziellen Paketen gehören, [FAIL] mit einer Meldung aus, die das Paket benennt, das sie bereitstellt. Das ist hier zu erwarten, und es kann das Gesamturteil auf UNHEALTHY kippen, obwohl Ihre Core-Einrichtung in Ordnung ist. Für diese Tutorials ist der Block Extensions das Signal, auf das es ankommt.

Falls etwas schiefgelaufen ist

Gleichen Sie Ihr Symptom zunächst mit diesen häufigen Fällen ab:

composer: command not found bedeutet, dass Composer fehlt oder nicht in Ihrem PATH liegt. Installieren Sie ihn von getcomposer.org und wiederholen Sie dann Schritt 1.
Failed opening required '.../vendor/autoload.php' bedeutet, dass das Skript außerhalb des Projektordners ausgeführt wurde oder die Installation nicht abgeschlossen wurde. Wechseln Sie in den Ordner aus Schritt 1 und führen Sie composer install aus.
Wenn Composer während Schritt 1 stoppt und eine fehlende PHP-Erweiterung benennt, aktivieren Sie diese Erweiterung in Ihrer php.ini. Bestätigen Sie sie mit php -m und wiederholen Sie dann die Installation.
Eine [FAIL]-Zeile im Block Extensions des Doctors benennt eine fehlende PHP-Erweiterung. Aktivieren Sie sie in php.ini, bestätigen Sie mit php -m und führen Sie den Doctor erneut aus. [FAIL]-Zeilen zu Fähigkeiten, die ein kommerzielles Paket benennen, sind bei der Core-Installation zu erwarten und erfordern hier kein Handeln.

Für alles Weitere beginnen Sie mit der Troubleshooting-Wissensdatenbank. Wenn ein Skript eine Exception auslöst, schlagen Sie deren Klasse in der Fehlerreferenz nach; die meisten Anfängerfehler erscheinen unter Allgemeine Fehler.

Weiter

Sie haben eine funktionierende Installation und Ihre erste gerenderte Datei. Fahren Sie fort mit Text, Schriften und Seitengrundlagen, um Seitengrößen, eingebaute Schriften, Farben und Ausrichtung zu steuern.