Overzicht van de NextPDF Laravel-integratie

In het kort

Het nextpdf/laravel-pakket verbindt de NextPDF PDF-engine met je Laravel 12-applicatie en registreert de containerbindingen voor je. Het bevat een Pdf-facade, een PdfResponse HTTP-helperobject en een GeneratePdfJob die in de wachtrij kan worden geplaatst. Laravel detecteert het pakket automatisch, dus je hoeft het niet handmatig te registreren.

Installeren

composer require nextpdf/laravel

De Composer-constraint is nextpdf/core: ^3.0 || ^5.2. Het pakket vereist ook laravel/framework: ^12.0 en php: >=8.4 <9.0. Zie /integrations/laravel/install/ voor de volledige procedure, inclusief het publiceren van de configuratie en optionele uitbreidingen.

Conceptueel overzicht

Het pakket bevindt zich tussen de Laravel-servicecontainer en de framework-onafhankelijke NextPDF-core. Het implementeert PDF-generatie niet opnieuw. In plaats daarvan past het het core-model NextPDF\Core\Document aan op de levenscyclus, configuratie, wachtrijen en HTTP-laag van Laravel.

Het onderstaande diagram volgt een verzoek vanaf je applicatiecode door het pakket heen tot in de gedeelde core-registers.

NextPDF Laravel request and render flow

De autoload-map heeft één PSR-4-vermelding. PSR-4 is de PHP Standard Recommendation voor autoloading, en de prefix NextPDF\Laravel\ wijst naar src/Laravel/. Onder PSR-4 komt een namespace-prefix overeen met een basismap, en de resterende klassenaam wordt afgebeeld op een bestandspad onder die map (PSR-4 §3). Vier productieklassen vallen onder deze prefix:

• NextPDF\Laravel\NextPdfServiceProvider — registreert bindingen en publiceert de configuratie.
• NextPDF\Laravel\Facades\Pdf — een statische proxy die een vers document uit de container resolvet.
• NextPDF\Laravel\Http\PdfResponse — maakt inline-, download- en gestreamde PDF-responses met een vaste set beveiligingsheaders.
• NextPDF\Laravel\Jobs\GeneratePdfJob — een job die je in de wachtrij kunt plaatsen en die op een worker een PDF bouwt en opslaat.

De serviceprovider implementeert DeferrableProvider, dus de bindingen worden pas geregistreerd wanneer je een van de gedeclareerde vermeldingen resolvet. Dit uitstel houdt het opstartpad van het framework slank. De provides()-methode van de provider somt de uitgestelde vermeldingen op, en de container leest deze lijst om elke sleutel terug te koppelen aan de provider.

Het resolven volgt het container-contract: wanneer een binding aanwezig is, geeft het resolven van de identifier de geregistreerde vermelding terug. PSR-11 is de PHP Standard Recommendation voor container-interoperabiliteit, en stelt dat twee opeenvolgende get()-aanroepen met dezelfde identifier verschillende waarden kunnen teruggeven, afhankelijk van de bindingsstrategie (PSR-11 §1.1.2). NextPDF maakt opzettelijk gebruik van dit gedrag. Registers zijn singletons, dus elke resolve-bewerking geeft dezelfde instantie terug. Documenten zijn via een factory gebonden, dus elke resolve-bewerking geeft een verse instantie terug. Zie /integrations/laravel/boot-and-discovery/ voor de volledige tabel met bindingslevensduren.

De architectuur is ontworpen voor langlevende workers, zoals Octane, RoadRunner en Swoole. Het lettertyperegister is een singleton met de levensduur van het proces: het pakket warmt het eenmalig op en vergrendelt het vervolgens, zodat geen enkel verzoek de gedeelde lettertypestatus kan wijzigen. Het afbeeldingsregister is een singleton met de levensduur van het proces, met een begrensde least-recently-used-cache (LRU). Omdat het pakket elk document altijd vanuit DocumentFactory aanmaakt, lekt veranderlijke status per verzoek nooit naar andere verzoeken.

Waarom documenten vers per verzoek zijn

De factory-binding geeft bij elke resolve-bewerking een nieuw Document terug, terwijl de gedeelde lettertype- en afbeeldingsregisters procesbreed blijven. Deze scheiding houdt langlevende workerprocessen (Octane, RoadRunner, Swoole) vrij van statuslekken tussen verzoeken, terwijl de parsekosten van lettertypen toch over meerdere verzoeken worden verdeeld.

API-oppervlak

Klasse	Publiek toegangspunt	Geeft terug	Doel
NextPdfServiceProvider	register(), boot(), provides()	void / array	Containerbindingen, configuratiepublicatie, lijst met uitgestelde vermeldingen
Facades\Pdf	statische proxy (addPage(), cell(), save(), …)	static / mixed	Resolvet PdfDocumentInterface per aanroep
Http\PdfResponse	inline(), download(), streamInline(), streamDownload()	Response / StreamedResponse	HTTP-responses met headers van het Open Worldwide Application Security Project (OWASP)
Jobs\GeneratePdfJob	dispatch(), handle(), then(), catch(), failed()	PendingDispatch / void / self	PDF-generatie in de wachtrij

Containersleutels die door de provider worden gebonden:

Sleutel	Levensduur	Resolvet naar
NextPDF\Contracts\FontRegistryInterface (alias FontRegistry)	singleton, vergrendeld	NextPDF\Typography\FontRegistry
NextPDF\Graphics\ImageRegistry	singleton, LRU-begrensd	ImageRegistry
NextPDF\Contracts\DocumentFactoryInterface (alias DocumentFactory)	singleton	NextPDF\Core\DocumentFactory
Psr\Http\Client\ClientInterface	singleton	SecurityAwareHttpClient die CurlHttpClient omhult
NextPDF\Security\Timestamp\TsaClient	scoped	TsaClient of null wanneer er geen timestamp-authority-URL (TSA) is
NextPDF\Contracts\SignerInterface	factory	DigitalSigner of null wanneer ondertekening is uitgeschakeld
NextPDF\Contracts\PdfDocumentInterface (alias nextpdf)	factory	NextPDF\Core\Document
NextPDF\Contracts\EInvoice\{Embedder,Validator,Profile,SchematronRunner}Interface	factory	resolvet alleen wanneer nextpdf/premium is geïnstalleerd

Codevoorbeeld — Snel starten

resource: README.md Quick Start (verified against src/Laravel/Facades/Pdf.php)

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

Zie /integrations/laravel/quickstart/ voor een uitvoerbaar voorbeeld dat beperkt is tot een controller.

Codevoorbeeld — Productie

Het productiepatroon resolvet het documentcontract uit de container in plaats van uit de facade. Daardoor blijft de aanroepplaats expliciet en testbaar. Zie /integrations/laravel/production-usage/ voor de volledige controller, inclusief dependency injection (DI) en foutafhandeling.

resource: src/Laravel/Http/PdfResponse.php (download factory)

<?php

declare(strict_types=1);

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

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Invoice', newLine: true);

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

Randgevallen en valkuilen

• De provider is uitgesteld, dus het resolven van een niet-gerelateerde containersleutel start NextPDF niet op. De bindingen verschijnen pas wanneer je een van de provides()-vermeldingen opvraagt.
• SignerInterface en TsaClient resolven standaard naar null wanneer je ondertekening of de timestamp-authority niet hebt geconfigureerd. Je code moet het resultaat op null controleren; ga er niet van uit dat er een instantie bestaat.
• De e-invoice-contractbindingen zijn altijd geregistreerd, maar ze resolven naar Premium-concretes die alleen bestaan wanneer nextpdf/premium is geïnstalleerd. Het resolven ervan zonder Premium veroorzaakt een class-not-found-fout, en de fout verschijnt bij de eerste resolve, niet bij het opstarten.
• De facade geeft per resolutie een vers document terug. Stel je twee statische Pdf::-aanroepen voor in hetzelfde verzoek, gescheiden door Pdf::clearResolvedInstances(): de aanroepen werken op verschillende documenten.

Controleer optionele ondertekeningsservices op null

SignerInterface en TsaClient zijn null totdat je ondertekening en een timestamp-authority configureert, dus alle code die deze sleutels resolvet moet de null-situatie afhandelen. Een ontbrekende null-controle faalt tijdens runtime, niet bij het opstarten.

Prestaties

Providerregistratie verloopt in O(1)-tijd. De provider bindt closures en construeert geen zware objecten, dus de constructiekosten worden uitgesteld tot de eerste resolve-bewerking. Het opwarmen van het lettertyperegister verloopt in O(f)-tijd, waarbij f het aantal vooraf geladen lettertypebestanden is, en gebeurt eenmaal per workerproces. Dit verdeelt de latentie van het eerste verzoek over langlevende workers. Het geheugenbudget per pagina voor dit overzicht is vastgelegd in het frontmatterveld performance_budget.

Beveiligingsnotities

PdfResponse past een vaste set headers van het Open Worldwide Application Security Project (OWASP) toe. Deze set omvat X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: default-src 'none', X-Robots-Tag en Referrer-Policy: no-referrer. GeneratePdfJob valideert zijn uitvoerpad aan de workerzijde, waardoor gemanipuleerde geserialiseerde payloads worden tegengegaan. Zie /integrations/laravel/security-and-operations/ voor het volledige dreigingsmodel en de implementatieconfiguratie.

De wachtrijpayload is niet-vertrouwde invoer

GeneratePdfJob hervalideert het uitvoerpad binnen handle() op de worker, niet alleen op het moment van dispatchen. Omdat de geserialiseerde payload in het wachtrijtransport (Redis of database) kan worden gemanipuleerd voordat de worker hem oppakt, wijst de controle aan de workerzijde path traversal, stream wrappers, null bytes en niet-PDF-doelen af.

Conformiteit

Bewering	Bron	Clausule	reference_id
Containerresolutie / levensduursemantiek	PSR-11 Container	§1.1.2
PSR-4 autoload-prefixafbeelding	PSR-4 Autoloader	§3

Commerciële context

Wanneer nextpdf/premium is geïnstalleerd, biedt dezelfde provider meer mogelijkheden: digitaal ondertekenen (PAdES B-B), PDF/A-archivering en e-invoice-contractbindingen. Deze worden via dezelfde containersleutels aangeboden, dus het hier gedocumenteerde Core-pakket heeft geen codewijziging nodig om deze mogelijkheden te benutten. Zie voor meer informatie https://nextpdf.dev/get-license/?intent=laravel-signing.

Zie ook

• /integrations/laravel/install/ — installatieprocedure en optionele uitbreidingen
• /integrations/laravel/quickstart/ — uitvoerbaar controllervoorbeeld
• /integrations/laravel/configuration/ — elke configuratiesleutel, geverifieerd tegen config/nextpdf.php
• /integrations/laravel/production-usage/ — controller met DI-bedrading, foutafhandeling, wachtrijgebruik
• /integrations/laravel/boot-and-discovery/ — automatische detectie en bindingslevensduren
• /integrations/laravel/security-and-operations/ — dreigingsmodel en implementatieconfiguratie