Laravel-API-Referenz

Auf einen Blick

Das Paket nextpdf/laravel bindet den Framework-unabhängigen Kern von NextPDF in eine Laravel-Anwendung ein. Es stellt vier direkt nutzbare Bausteine bereit: die Facade Pdf für schnelles Authoring, die Container-Bindung PdfDocumentInterface für die injizierbare Dokumenterstellung, den Helper PdfResponse, der ein fertiges Dokument in eine HTTP-Response umwandelt, und den Queue-Job GeneratePdfJob für die Generierung außerhalb des Request-Kontexts. Der NextPdfServiceProvider registriert alle Bindungen und wird automatisch erkannt, sodass keine manuelle Einrichtung nötig ist. Die Konfiguration in config/nextpdf.php steuert Standardwerte, Schriften, Queueing sowie die optionalen Signatur- und TSA-Funktionen.

Starten Sie hier: Um ein PDF direkt aus einem Controller zu senden, erstellen Sie ein Dokument und geben PdfResponse::download($document, 'file.pdf') zurück — siehe das erste Beispiel weiter unten.

Häufige Aufgaben

Die folgenden Snippets decken die drei Abläufe ab, die Sie voraussichtlich zuerst nutzen werden. Jedes Snippet ist gegen den Paket-Quellcode verifiziert; die vollständigen Tabellen pro Symbol folgen.

Ein herunterladbares PDF aus einem Controller zurückgeben — die häufigste Aufgabe:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

Was es bewirkt: Ein frisches Dokument wird injiziert, eine Zeile geschrieben und eine attachment-Response mit Content-Type: application/pdf und den OWASP-Security-Headern zurückgegeben. Ersetzen Sie download() durch inline(), um stattdessen eine Vorschau im Browser anzuzeigen.

Mit der Facade Pdf erstellen und speichern — der kürzeste Weg für Skripte und kurze Abläufe:

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

Was es bewirkt: Die Facade löst ein frisches Dokument aus dem Container auf, schreibt eine Zelle und speichert das fertige PDF auf der Festplatte.

Ein PDF außerhalb des Request-Threads mit GeneratePdfJob generieren:

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

Was es bewirkt: Die Generierung wird zur Ausführung auf einem Worker in die Queue gestellt. Die Builder-Closure erhält ein vom Container aufgelöstes Dokument und gibt es zurück. Der Job validiert vor dem Speichern den .pdf-Ausgabepfad. Queue-Name, Timeout und Connection stammen aus config('nextpdf.queue.*').

Facade

Die Facade Pdf leitet statische Aufrufe an ein frisches Kern-Document weiter; nutzen Sie sie in kurzen Controller-Abläufen, wenn der statische Stil gut lesbar ist. Jeder Aufruf ist eine weitergeleitete Dokumentmethode.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
NextPDF\Laravel\Facades\Pdf	keine; der statische Facade-Accessor ermittelt NextPDF\Contracts\PdfDocumentInterface	Laravel löst die aktuelle Container-Bindung für das Dokument-Interface auf.	Die zugrunde liegende Fluent-API des Kern-Dokuments.	Fehler bei der Laravel-Container-Bindung, wenn der Provider nicht registriert ist.	Nutzen Sie sie für kurze Controller-Abläufe. Für Services und Jobs bevorzugen Sie Constructor Injection.
Pdf::setTitle(string $title)	title: Dokumenttitel.	Ersetzt jeden vorherigen Titel.	static	Fehler bei der Validierung im Kern oder beim Schreiben.	An das Kern-Document weitergeleitet.
Pdf::setAuthor(string $author)	author: Autor-Metadaten des Dokuments.	Ersetzt jeden vorherigen Autor.	static	Fehler bei der Metadaten-Validierung im Kern.	Für anwendungsweite Metadaten bevorzugen Sie konfigurierte Standardwerte.
Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)	size: optionale Seitengröße; orientation: standardmäßig Portrait.	Verwendet die konfigurierte oder standardmäßige Seitengröße, wenn size weggelassen wird.	static	Fehler bei der Seitenvalidierung im Kern.	Verwenden Sie eine explizite PageSize, wenn die Ausgabegröße wichtig ist.
Pdf::setFont(string $family, string $style = '', float $size = 12.0)	Schriftfamilie, Stil und Punktgröße.	Leerer Stil und Schriftgröße 12 pt.	static	Fehler in der Font-Registry oder bei der Kodierung.	Laden Sie Produktionsschriften über nextpdf.preload_fonts vor, wenn Latenz wichtig ist.
Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)	Zellbox, Text, Rahmen-Flag, Zeilenumbruch-Flag, Ausrichtung.	Leerer Text, kein Rahmen, kein Zeilenumbruch, linksbündige Ausrichtung.	static	Fehler beim Layout oder bei der Textkodierung.	Verwenden Sie sie für einfache Ausgabe mit festem Layout.
Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)	Zellbreite, Zeilenhöhe, Text, Rahmen-Flag, Ausrichtung.	Kein Rahmen und linksbündige Ausrichtung.	static	Fehler beim Layout oder bei der Textkodierung.	Verwenden Sie sie, wenn Text innerhalb einer festen Breite umbrechen soll.
Pdf::writeHtml(string $html)	html: HTML-Fragment.	Rendert in die aktuelle Seite und erstellt bei Bedarf eine neue.	static	Fehler beim HTML-Rendering im Kern.	Wenden Sie Richtlinien für Eingabegröße und Ressourcen an, bevor Sie nicht vertrauenswürdiges HTML akzeptieren.
Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)	Dateipfad und optionales Platzierungsrechteck.	Lässt das Kern-Dokument die aktuelle Position und die intrinsische Größe wählen, wenn Koordinaten weggelassen werden.	static	Fehler beim Dekodieren des Bildes, beim Pfad oder beim Layout.	Validieren Sie die Richtlinie für Bildquellen, bevor Sie von Nutzern angegebene Pfade akzeptieren.
Pdf::output(?string $filename = null, OutputDestination $dest = Inline)	filename: optionaler Name; dest: Ausgabeziel.	Inline-Ausgabe, wenn das Ziel weggelassen wird.	string	Fehler bei der Serialisierung im Kern.	Für Laravel-HTTP-Responses bevorzugen Sie PdfResponse.
Pdf::save(string $path)	path: Ziel im Dateisystem.	Schreibt das fertige PDF auf die Festplatte.	void	Fehler im Dateisystem oder beim Schreiben im Kern.	Validieren Sie Ausgabeverzeichnisse im Anwendungscode.
Pdf::getPdfData()	keine.	Materialisiert das PDF in den Arbeitsspeicher.	string	Fehler bei der Serialisierung im Kern.	Verwenden Sie sie, wenn ein anderes Framework-Objekt den Response-Body halten muss.

Service Provider und Bindungen

Verwenden Sie diese Tabelle, wenn Sie einen Container-Eintrag direkt auflösen oder überschreiben müssen — etwa um DocumentFactoryInterface in einen Service zu injizieren oder um zu prüfen, welche Services provides() aufschiebt.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
NextPdfServiceProvider::register()	keine.	Führt config/nextpdf.php zusammen und registriert Registries, Document Factory, Dokument-Bindung, HTTP-Client, TSA-Client, Signer und optionale E-Invoice-Contracts.	void	Fehler beim Auflösen im Container oder bei optionalen Klassen, wenn eine Funktion genutzt wird.	FontRegistryInterface und ImageRegistry werden geteilt; Dokumente werden immer neu erstellt.
NextPdfServiceProvider::boot()	keine.	Validiert die erforderlichen PHP-Erweiterungen und veröffentlicht nextpdf-config im Konsolenmodus.	void	RuntimeException, wenn eine erforderliche Erweiterung nicht verfügbar ist.	Erforderliche Erweiterungen sind mbstring und zlib.
NextPdfServiceProvider::provides()	keine.	Gibt die IDs der aufgeschobenen Services zurück.	array<string>	keine erwartet.	Umfasst PdfDocumentInterface, DocumentFactoryInterface, FontRegistryInterface, SignerInterface, TsaClient, ClientInterface und nextpdf.
PdfDocumentInterface / nextpdf	aus dem Laravel-Container aufgelöst.	Erstellt ein verwerfbares Document aus DocumentFactoryInterface und wendet dann konfigurierte Standardwerte sowie optionale PDF/A- oder Artisan-Einstellungen an.	NextPDF\Core\Document	Fehler bei optionalen Erweiterungen, wenn sie konfiguriert, aber nicht verfügbar sind.	Lösen Sie für jeden Request oder Job ein neues Dokument auf.
DocumentFactoryInterface	aus dem Laravel-Container aufgelöst.	Singleton-Factory, die sich die prozessweit langlebigen Font- und Image-Registries teilt.	DocumentFactoryInterface	Fehler beim Einrichten der Registry.	Verwenden Sie diese Bindung für explizite Dependency Injection.
SignerInterface	aus dem Laravel-Container aufgelöst.	Gibt null zurück, sofern nicht nextpdf.signature.enabled und Zertifikatspfade konfiguriert sind.	`SignerInterface	null`	Fehler beim Laden des Zertifikats oder bei der Validierung auf Signaturebene.

Konfiguration

Verwenden Sie diese Tabelle, um die zur Laufzeit relevanten nextpdf.*-Schlüssel nachzuschlagen, die die Bindungen lesen; die vollständige Referenz pro Schlüssel mit Umgebungsvariablen und Standardwerten finden Sie unter /integrations/laravel/configuration/.

Schlüssel	Typ	Standardverhalten	Hinweise
nextpdf.fonts_path	string	Verwendet die Schriften aus den Laravel-Ressourcen, wenn weggelassen.	Verzeichnis für eigene Schriften und Warmup.
nextpdf.cache_path	string	Cache-Pfad der Anwendung.	Halten Sie ihn für den PHP-Worker schreibbar.
nextpdf.preload_fonts	list<string>	Leere Liste.	Wird beim Erstellen der Registry vorgewärmt, danach wird die Registry gesperrt.
nextpdf.image_cache_mb	int	Begrenzte Größe des Image-Cache.	Begrenzt den Arbeitsspeicher des prozessweit langlebigen Image-Cache.
nextpdf.defaults.*	array	Creator NextPDF, Sprache en, optionaler Autor und Layout-Standardwerte.	Wird auf jedes frische Dokument angewendet.
nextpdf.artisan.*	array	Der Chrome-Renderer ist deaktiviert, sofern er nicht installiert und konfiguriert ist.	Wird auf ChromeRendererConfig::fromArray() abgebildet.
nextpdf.signature.*	array	Signieren ist standardmäßig deaktiviert.	Zertifikat, privater Schlüssel, Passwort, zusätzliche Zertifikate und Signaturebene.
nextpdf.tsa.*	array	TSA ist deaktiviert, wenn die URL leer ist.	Unterstützt Anmeldeinformationen, mTLS-Dateien, Timeout, Public-Key-Pins und HTTP-Richtlinie.
nextpdf.ocsp_cache.*	array	Der OCSP-Cache ist mit der konfigurierten TTL aktiviert.	Wird von den Signaturvalidierungs-Abläufen verwendet, wenn verfügbar.

HTTP-Responses

Verwenden Sie diese Tabelle, wenn Sie ein fertiges Dokument über HTTP zurückgeben und zwischen Inline-Anzeige, Attachment-Download oder gestreamter Ausgabe wählen müssen.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: erstelltes Dokument; filename: Content-Disposition-Dateiname.	Leere Dateinamen werden zu document.pdf normalisiert.	Illuminate\Http\Response	Fehler bei der Serialisierung im Kern oder beim Konstruieren der Response.	Setzt den PDF-Content-Type und defensive Header.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Wie inline; die Disposition ist attachment.	Response für den Browser-Download.	Illuminate\Http\Response	Wie inline.	Verwenden Sie sie für explizite Datei-Downloads.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Wie inline.	Materialisiert die PDF-Bytes und gibt dann 64-KB-Chunks aus.	Symfony\Component\HttpFoundation\StreamedResponse	Wie inline.	Dies ist gestreamte HTTP-Ausgabe, kein Zero-Copy-Rendering.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Wie streamInline; die Disposition ist attachment.	Download-Stream-Response.	StreamedResponse	Wie streamInline.	Erzwingen Sie Grenzen für Eingabe- und Ausgabegröße vor dem Rendern.

Queue-Job

Verwenden Sie diese Tabelle, wenn Sie die Generierung aus dem Request-Thread auslagern; sie deckt das Konstruieren, Dispatchen und Anhängen von Erfolgs- oder Fehler-Callbacks an GeneratePdfJob ab.

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder schlägt fehl mit	Hinweise
new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)	outputPath: Ziel-.pdf; builder: erhält ein PdfDocumentInterface; Callbacks sind optional.	Queue-Name, Timeout und Connection werden aus config('nextpdf.queue.*') gelesen.	Job-Instanz.	Serialisierungsfehler, wenn der Builder oder die Callbacks nicht serialisiert werden können.	Der Builder muss das konfigurierte Dokument zurückgeben.
GeneratePdfJob::handle()	keine.	Löst PdfDocumentInterface auf, wendet den Builder an, validiert den Ausgabepfad und speichert dann.	void	InvalidArgumentException bei unsicheren Ausgabepfaden; Schreibfehler im Kern.	Lehnt Stream-Wrapper, Null-Bytes, ..-Segmente und Nicht-.pdf-Pfade ab.
GeneratePdfJob::failed(Throwable $exception)	exception: Fehlerursache.	Ruft den konfigurierten Fehler-Callback auf, falls vorhanden.	void	Callback-Fehler.	Halten Sie Callbacks idempotent.
GeneratePdfJob::then(callable $callback)	callback: erhält den Ausgabepfad.	Ersetzt den Erfolgs-Callback.	self	Fehler bei serialisierbaren Closures.	Fluent-Helper für die Dispatch-Einrichtung.
GeneratePdfJob::catch(callable $callback)	callback: erhält das geworfene Throwable.	Ersetzt den Fehler-Callback.	self	Fehler bei serialisierbaren Closures.	Verwenden Sie ihn für Alerting oder kompensierendes Cleanup.

Entwicklungshinweise

• PdfResponse ruft vor dem Konstruieren der Response immer getPdfData() auf. Es ist kein Lazy-Document-Builder.
• Queue-Payloads können in gemeinsam genutzten Transporten manipuliert werden; beschränken Sie Ausgabepfade auf ein anwendungseigenes Verzeichnis.
• Verwenden Sie ein frisches Dokument pro Request oder Job. Verwenden Sie ein Dokument nicht über mehrere Requests hinweg erneut.