NextPDF Laravel-snelstart

In een oogopslag

In deze tutorial maakt u vanuit een controller een downloadbaar Portable Document Format-bestand (PDF). Vervolgens verplaatst u dezelfde verwerking naar een job in de wachtrij. Elk fragment komt overeen met gedrag dat de testsuite van het package vastlegt.

Installeren

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

Conceptueel overzicht

Drie toegangspunten dekken vrijwel elk Laravel-gebruiksscenario. Met de facade bent u het snelst op weg. PdfResponse zet een document om naar een Hypertext Transfer Protocol-respons (HTTP). Een job in de wachtrij haalt zware generatie uit de request-thread, zodat u er niet op hoeft te wachten. Deze tutorial behandelt elk toegangspunt achtereenvolgens. De productieklare versies voegen foutafhandeling toe en staan op /integrations/laravel/production-usage/.

Codevoorbeeld — snelstart

1. Facade

De facade haalt bij elke aanroep een nieuw document uit de container. De container is het serviceregister van Laravel. Dit fragment komt overeen met het gedrag dat tests/Unit/Laravel/Facades/PdfTest.php vastlegt.

<?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-respons vanuit een controller

PdfResponse::download() retourneert een Illuminate\Http\Response met Content-Type: application/pdf, een attachment-dispositie en Open Worldwide Application Security Project-beveiligingsheaders (OWASP). tests/Unit/Laravel/Http/PdfResponseTest.php controleert de statuscode, het contenttype, het prefix van de dispositie en de headers.

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

Vervang download() door inline() om een inline voorbeeld in de browser te tonen. Gebruik voor grote documenten streamInline() of streamDownload(). Deze verzenden de PDF in deterministische blokken van 64 KB.

3. Generatie via de wachtrij

GeneratePdfJob bouwt een PDF en slaat die op via een queue worker. De builder-closure ontvangt het uit de container opgehaalde document en retourneert het geconfigureerde document. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php bevestigt dat de job het bestand op exact het opgegeven uitvoerpad aanmaakt.

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

Het uitvoerpad moet eindigen op .pdf. De job valideert het pad op de worker voordat er wordt geschreven.

Codevoorbeeld — productie

De productieversies voegen expliciete foutafhandeling, succes- en faalcallbacks voor de job en een getypeerde exception-strategie toe. Deze worden volledig gedocumenteerd op /integrations/laravel/production-usage/.

Randgevallen en valkuilen

De facade retourneert bij elke container-resolutie een andere document-instantie. Cache Pdf::getFacadeRoot() niet over meerdere logische documenten heen.
Als u een lege bestandsnaam doorgeeft aan een willekeurige PdfResponse-factory, valt deze terug op de standaardwaarde document.pdf. De testsuite voor responses legt deze standaardwaarde vast.
Bestandsnamen met niet-ASCII-tekens krijgen automatisch een RFC 5987-filename*=-parameter. ASCII-namen niet.
GeneratePdfJob wijst path traversal, stream wrappers, null bytes en elke andere extensie dan .pdf af. De job werpt InvalidArgumentException op de worker.

Prestaties

Een document van één pagina wordt ruim binnen het wall-budget per pagina uit de front matter gegenereerd. Door de generatie te verplaatsen naar GeneratePdfJob verdwijnt de bouwtijd van de PDF volledig uit de HTTP-request. De request keert terug zodra de job is verzonden.

Beveiligingsopmerkingen

PdfResponse-factory’s passen een vaste set OWASP-headers toe. Ze schonen ook de bestandsnaam van de download op. De job in de wachtrij valideert het uitvoerpad. Gedetailleerde dekking van bedreigingen vindt u op /integrations/laravel/security-and-operations/.

Conformiteit

Voor deze tutorial geldt geen normatieve standaard. Elk fragment wordt geverifieerd tegen de broncode van het package en de bijbehorende test onder tests/.

Commerciële context

Ondertekende uitvoer en PDF/A-uitvoer zijn beschikbaar met nextpdf/premium als optionele Enterprise-mogelijkheid. Voor het hier gedocumenteerde Core-package is geen codewijziging nodig om dit over te nemen. Zie https://nextpdf.dev/get-license/?intent=laravel-signing.

Zie ook

/integrations/laravel/install/ — configuratie installeren en publiceren
/integrations/laravel/production-usage/ — controller en job aangesloten via dependency injection en foutafhandeling
/integrations/laravel/configuration/ — configuratiesleutels die hier worden gebruikt
/integrations/laravel/overview/ — architectuur en levensduur van bindings