Laravel-ontwikkelaarsgids

In het kort

Het Laravel-pakket stemt NextPDF af op Laravel-conventies zonder de levenscyclus van het kerndocument te wijzigen. De container beheert gedeelde registers en factory’s. Elk PDF-document is bedoeld voor eenmalig gebruik: u bouwt, retourneert, streamt of slaat het maar één keer op.

Gebruik deze handleiding wanneer u applicatieservices, queue-jobs, responsstromen of testdekking voor nextpdf/laravel ontwerpt.

Architectuurgrens

Laag	Eigendom van	Verantwoordelijkheid	Plaats hier niet
Controller	Applicatie	Autoriseer het verzoek, kies een document-builder en retourneer een respons.	PDF-lay-outregels die over meerdere use cases worden gedeeld.
Applicatieservice	Applicatie	Verzamel domeingegevens en roep de document-buildercode aan.	Bootlogica van de container of pakketconfiguratie.
Document-builder	Applicatie	Vertaal domeingegevens naar NextPDF-documentaanroepen.	Request-objecten, Eloquent-querylogica of details van het queue-transport.
Laravel-integratie	nextpdf/laravel	Bindt factory’s, registers, signer, TSA-client, facade, responses en queue-job.	Bedrijfsspecifieke opslagpaden of tenantbeleid.
Kernengine	nextpdf/nextpdf	Bouwt de PDF en serialiseert deze.	Beleid voor Laravel-respons, queue of bestandssysteem.

Runtime-levenscyclus

Fase	Gedrag	Actie van de ontwikkelaar
Registratie van de service provider	NextPdfServiceProvider::register() registreert gedeelde registers, de document-factory, de documentbinding, de HTTP-client, de time-stamping authority (TSA)-client, de signer en optionele e-invoice-contracten.	Publiceer en controleer config/nextpdf.php voordat u naar productie gaat.
Documentresolutie	De Pdf-facade en de PdfDocumentInterface-binding lossen een vers document op via DocumentFactoryInterface.	Los één document per verzoek, commando of queued job op.
Opstellen	Applicatiecode roept de kerndocument-API’s aan via de facade of het geïnjecteerde document.	Houd het extraheren van domeingegevens buiten de document-builder.
Eindoutput	PdfResponse produceert HTTP-output, of het document wordt op schijf opgeslagen.	Kies per document één eindoutputpad.
Queue-uitvoering	GeneratePdfJob bouwt het document opnieuw op in de worker en valideert het outputpad opnieuw.	Geef scalaire context door en houd callbacks idempotent.

Aanbevolen applicatiestructuur

Pad	Doel
app/Pdf/Builders/*	Pure document-builders. Ze ontvangen gegevens en retourneren een voltooid document.
app/Pdf/Data/*	Kleine data transfer objects (DTO’s) met al geautoriseerde documentinvoer.
app/Services/*	Applicatieorkestratie, queries, overdracht van autorisatie en selectie van het opslagpad.
app/Jobs/*	Optionele wrappers rond GeneratePdfJob wanneer de applicatie benoemde jobs nodig heeft.
tests/Feature/Pdf/*	Tests voor HTTP-respons, queue-dispatch en autorisatie.
tests/Unit/Pdf/*	Builder-tests met kleine, deterministische invoer.

Houd builders onafhankelijk van Laravel-request-objecten. U moet dezelfde builder vanuit een controller, commando, test of queue-worker met dezelfde invoer kunnen aanroepen.

<?php

namespace App\Pdf\Builders;

use App\Pdf\Data\InvoicePdfData;
use NextPDF\Contracts\PdfDocumentInterface;

final readonly class InvoicePdfBuilder
{
    public function build(PdfDocumentInterface $pdf, InvoicePdfData $data): PdfDocumentInterface
    {
        $pdf->setTitle($data->title)
            ->addPage()
            ->setFont('dejavusans', '', 12)
            ->writeHtml($data->html);

        return $pdf;
    }
}

Synchroon responspatroon

Gebruik constructor-injectie wanneer de PDF-flow deel uitmaakt van de applicatielogica. Gebruik de facade alleen voor korte controllerflows waarin de statische stijl makkelijker leesbaar is.

<?php

namespace App\Http\Controllers;

use App\Pdf\Builders\InvoicePdfBuilder;
use App\Pdf\Data\InvoicePdfData;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final readonly class DownloadInvoiceController
{
    public function __invoke(
        PdfDocumentInterface $pdf,
        InvoicePdfBuilder $builder,
    ) {
        $document = $builder->build(
            $pdf,
            InvoicePdfData::fromInvoiceId(1234),
        );

        return PdfResponse::download($document, 'invoice-1234.pdf');
    }
}

Respons-helpers materialiseren de documentbytes voordat ze de Laravel-respons opbouwen. Het zijn respons-helpers, geen background renderers.

Queue-patroon

GeneratePdfJob accepteert een builder-callable en een outputpad. De job valideert onveilige paden tijdens de uitvoering. Applicatiecode moet vóór dispatch nog steeds een tenantveilige opslagroot kiezen.

<?php

use App\Pdf\Builders\QueuedInvoiceBuilder;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    outputPath: storage_path('app/pdfs/invoice-1234.pdf'),
    builder: [QueuedInvoiceBuilder::class, 'build'],
)->onQueue(config('nextpdf.queue.queue', 'pdf'));

Houd queue-callbacks klein. Schrijf persistente status bij voorkeur weg vanuit een applicatiejob-listener in plaats van complexe closures in de queue-payload op te slaan.

Uitbreidingspunten

Uitbreidingspunt	Gebruik het voor	Beperking
PdfDocumentInterface-binding	Vervang of decoreer documentaanmaak voor applicatiebrede standaardwaarden.	Moet een verse documentinstantie retourneren.
DocumentFactoryInterface	Maak verse documenten expliciet aan in services en tests.	Cache geretourneerde documenten niet.
config/nextpdf.php	Standaardwaarden, queue-instellingen, Chrome-renderer-instellingen, signing-hooks, TSA, OCSP-cache.	Behandel omgevingsvariabelen als deployment-configuratie, niet als request-invoer.
GeneratePdfJob-builder	Bouw documenten asynchroon.	De callable moet serialiseerbaar zijn door het queue-transport van Laravel.
Success/failure-callbacks	Melding of opschoning na generatie.	Houd callbacks idempotent en bewust van neveneffecten.
Optionele Premium-contracten	E-invoice-embedder, -validator, -profiel en Schematron-runner.	Resolveer ze alleen waar het optionele pakket is geïnstalleerd en gelicentieerd.

Ontwikkelworkflow

1. Bouw het eerste document synchroon in een controller of feature-test.
2. Verplaats lay-outcode naar een builder-klasse onder app/Pdf/Builders.
3. Verplaats query- en autorisatielogica naar een applicatieservice.
4. Voeg PdfResponse-tests toe voor headers en bestandsnamen.
5. Verplaats trage of grootschalige generatie naar GeneratePdfJob.
6. Voeg queue-tests toe voor geserialiseerde context, het beleid voor het outputpad en foutafhandeling.
7. Meet het geheugengebruik en de rendertijd met representatieve productiegegevens.

Foutafhandeling

Fout	Waar deze afgehandeld moet worden	Aanbevolen respons
Ongeldig verzoek of niet-geautoriseerd document	Controller of policy.	Retourneer de normale autorisatie- of validatierespons van de applicatie.
Ontbrekend lettertype of ongeldige afbeelding	Builder-test en applicatielogging.	Laat het verzoek of de job mislukken; produceer geen onvolledige PDF’s.
Onveilig outputpad	Applicatie-opslagservice en GeneratePdfJob.	Weiger vóór dispatch en vertrouw op validatie aan de workerzijde als defense in depth.
Signing- of TSA-fout	Grens van de signing-service.	Bepaal of het document onondertekend mag zijn; standaard fail closed voor gereguleerde documenten.
Queue-timeout	Configuratie en observability van de queue-worker.	Probeer alleen opnieuw wanneer de builder deterministisch is en het outputpad veilig kan worden overschreven.

Veilige standaardwaarden

Aandachtspunt	Standaardwaarde	Wanneer overschrijven
Queue-naam	pdf	Gebruik een toegewijde queue wanneer de generatie concurreert met gebruikersgerichte jobs.
Job-timeout	120 seconden	Verhoog dit alleen na het meten van de documentgrootte en de workercapaciteit.
Bestandsnaam van de respons	document.pdf	Gebruik opgeschoonde bedrijfsidentificatoren.
Lettertyperegister	Gedeeld en vergrendeld na warmup.	Voeg preload_fonts toe voor lettertypen die op hot paths worden gebruikt.
Afbeeldingsregister	Gedeelde, begrensde cache.	Verlaag image_cache_mb voor workers met beperkt geheugen.
Chunking van gestreamde respons	Chunks van 64 KB.	Vertrouw niet op chunkgrenzen; dat is een outputdetail.

Testchecklist

• Controller-tests asserteren Content-Type, Content-Disposition en defensieve headers.
• Builder-tests gebruiken deterministische DTO’s en bevragen de database niet.
• Queue-tests asserteren dat de builder een vers document ontvangt.
• Padtests dekken traversal, stream-wrapper, null-byte en de afwijzing van niet-.pdf-bestanden.
• Worker-tests renderen representatieve documenten onder dezelfde geheugenlimiet als productie.
• Optionele signing-tests dekken een ontbrekend certificaat, een ongeldig wachtwoord, een onbeschikbare TSA en het geconfigureerde handtekeningniveau.