NextPDF Laravel-Schnellstart

Auf einen Blick

In diesem Tutorial erstellen Sie ein herunterladbares PDF aus einem Controller. Anschließend verlagern Sie dieselbe Arbeit in einen Queue-Job. Jedes Snippet entspricht einem Verhalten, das die Testsuite des Pakets absichert.

Installation

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Konzeptioneller Überblick

Drei Einstiegspunkte decken nahezu jeden Laravel-Anwendungsfall ab. Die Facade bietet Ihnen den schnellsten Einstieg. PdfResponse verwandelt ein Dokument in eine HTTP-Response. Ein Queue-Job verlagert die aufwendige Generierung aus dem Request-Thread heraus, sodass die Nutzerin oder der Nutzer nicht darauf warten muss. Dieses Tutorial führt Sie nacheinander durch alle drei. Die produktionsreifen Versionen mit ergänzter Fehlerbehandlung finden Sie unter /integrations/laravel/production-usage/.

Codebeispiel – Schnellstart

1. Facade

Die Facade löst bei jedem Aufruf ein frisches Dokument aus dem Container auf. Der Container ist die Service-Registry von Laravel. Dieses Snippet entspricht dem Verhalten, das tests/Unit/Laravel/Facades/PdfTest.php absichert.

<?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'));

2. Download-Response aus einem Controller

PdfResponse::download() gibt eine Illuminate\Http\Response mit Content-Type: application/pdf, einer attachment-Disposition und den OWASP-Sicherheits-Headern zurück. tests/Unit/Laravel/Http/PdfResponseTest.php prüft den Statuscode, den Content-Type, das Disposition-Präfix und die Header.

<?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(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

Für eine Inline-Vorschau im Browser ersetzen Sie download() durch inline(). Verwenden Sie für große Dokumente streamInline() oder streamDownload(). Diese senden das PDF in deterministischen 64-KB-Chunks.

3. Generierung über die Queue

GeneratePdfJob erzeugt und speichert ein PDF auf einem Queue-Worker. Die Builder-Closure erhält das vom Container aufgelöste Dokument und gibt das konfigurierte Dokument zurück. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php bestätigt, dass der Job die Datei exakt am Ausgabepfad anlegt.

<?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),
);

Der Ausgabepfad muss auf .pdf enden. Der Job validiert den Pfad auf dem Worker, bevor er die Datei schreibt.

Codebeispiel – Produktion

Die Produktionsversionen ergänzen explizite Fehlerbehandlung, Erfolgs- und Fehler-Callbacks am Job sowie eine typisierte Exception-Strategie. Sie sind vollständig unter /integrations/laravel/production-usage/ dokumentiert.

Sonderfälle & Stolperfallen

Die Facade gibt bei jeder Auflösung eine andere Dokument-Instanz zurück. Speichern Sie Pdf::getFacadeRoot() nicht über logische Dokumente hinweg im Cache.
Wenn einer beliebigen PdfResponse-Factory ein leerer Dateiname übergeben wird, verwendet die Response standardmäßig document.pdf. Die Testsuite für Responses sichert diesen Standardwert ab.
Nicht-ASCII-Dateinamen erhalten automatisch einen RFC 5987-filename*=-Parameter. ASCII-Namen erhalten ihn nicht.
GeneratePdfJob weist Path-Traversal, Stream-Wrapper, Null-Bytes und jede Endung außer .pdf zurück. Der Job wirft auf dem Worker eine InvalidArgumentException.

Performance

Ein einseitiges Dokument wird deutlich innerhalb des im Front-Matter angegebenen Wall-Budgets pro Seite generiert. Die Verlagerung der Generierung in GeneratePdfJob entfernt die PDF-Build-Zeit vollständig aus dem HTTP-Request. Der Request wird abgeschlossen, sobald der Job dispatcht wurde.

Sicherheitshinweise

PdfResponse-Factories wenden einen festen Satz von OWASP-Headern an. Außerdem bereinigen sie den Download-Dateinamen. Der Queue-Job validiert seinen Ausgabepfad. Eine detaillierte Abdeckung der Bedrohungen finden Sie unter /integrations/laravel/security-and-operations/.

Konformität

Für dieses Tutorial gilt kein normativer Standard. Jedes Snippet ist anhand des Quellcodes des Pakets verifiziert. Es ist außerdem durch den entsprechenden Test unter tests/ verifiziert.

Kommerzieller Kontext

Signierte Ausgabe und PDF/A-Ausgabe sind mit nextpdf/premium verfügbar. Dies ist eine optionale Enterprise-Funktion. Für die Übernahme ist im hier dokumentierten Core-Paket keine Code-Änderung erforderlich. Siehe https://nextpdf.dev/get-license/?intent=laravel-signing.

Siehe auch

/integrations/laravel/install/ – Installation und Veröffentlichung der Konfiguration
/integrations/laravel/production-usage/ – per DI verdrahteter Controller und Job mit Fehlerbehandlung
/integrations/laravel/configuration/ – hier verwendete Konfigurationsschlüssel
/integrations/laravel/overview/ – Architektur und Lebensdauern von Bindungen