Laravel API-referentie

In een oogopslag

Het pakket nextpdf/laravel verbindt de framework-onafhankelijke NextPDF-core met een Laravel-applicatie. Je spreekt vier toegangspunten rechtstreeks aan: de Pdf-facade voor korte authoring-flows, de containerbinding PdfDocumentInterface voor injecteerbare documentcreatie, de helper PdfResponse voor HTTP-responses op basis van voltooide documenten, en de queue-job GeneratePdfJob voor generatie buiten de request om. De NextPdfServiceProvider registreert elke binding en wordt automatisch gedetecteerd, zodat je geen handmatige configuratie nodig hebt. Configuratie in config/nextpdf.php bepaalt standaardwaarden, lettertypen, queues en optionele functies voor ondertekening en time-stamp authority (TSA).

Begin hiermee: om een Portable Document Format-bestand (PDF) rechtstreeks vanuit een controller te verzenden, bouw je een document op en retourneer je PdfResponse::download($document, 'file.pdf'). Het eerste voorbeeld hieronder toont deze flow.

Veelvoorkomende taken

De fragmenten hieronder behandelen de drie flows die je doorgaans als eerste gebruikt. Elk fragment is geverifieerd aan de hand van de pakketbroncode; volledige tabellen per symbool volgen daarna.

Retourneer een downloadbare PDF vanuit een controller. Dit is de meest voorkomende taak:

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

Wat het doet: injecteert een vers document, schrijft één regel en retourneert een attachment-response met Content-Type: application/pdf en de beveiligingsheaders van het Open Worldwide Application Security Project (OWASP). Gebruik inline() in plaats van download() om de PDF in de browser te bekijken.

Maak en bewaar een PDF met de Pdf-facade. Dit is de kortste route voor scripts en korte flows:

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

Wat het doet: de facade haalt een vers document uit de container op, schrijft één cel en bewaart de voltooide PDF op schijf.

Genereer een PDF buiten de request-thread om met GeneratePdfJob:

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

Wat het doet: zet de generatie in de wachtrij op een worker. De builder-closure ontvangt een document dat door de container is omgezet en retourneert het. De job valideert het .pdf-uitvoerpad vóór het opslaan. Queuenaam, time-out en verbinding komen uit config('nextpdf.queue.*').

Facade

De Pdf-facade fungeert als statische proxy voor een vers core-Document. Gebruik de facade in korte controller-flows wanneer de statische stijl duidelijk blijft. Elke rij vermeldt één gedelegeerde documentmethode.

Symbool	Parameters	Standaardgedrag	Retourneert	Genereert fout of mislukt met	Opmerkingen
`NextPDF\Laravel\Facades\Pdf`	geen; de statische facade-accessor wordt omgezet naar `NextPDF\Contracts\PdfDocumentInterface`	Laravel zet de huidige containerbinding voor de documentinterface om.	De onderliggende fluent API van het core-document.	Containerbindingsfout in Laravel als de provider niet is geregistreerd.	Gebruik de facade voor korte controller-flows. Geef bij services en jobs de voorkeur aan constructor-injectie.
`Pdf::setTitle(string $title)`	`title`: documenttitel.	Vervangt een eventuele bestaande titel.	`static`	Validatie- of schrijffouten in de core.	Delegeert naar het core-`Document`.
`Pdf::setAuthor(string $author)`	`author`: metadata van de documentauteur.	Vervangt een eventuele eerdere auteur.	`static`	Validatiefouten in core-metadata.	Geef voor applicatiebrede metadata de voorkeur aan geconfigureerde standaardwaarden.
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`: optioneel paginaformaat; `orientation`: standaard `Portrait`.	Gebruikt het geconfigureerde of standaardpaginaformaat wanneer `size` wordt weggelaten.	`static`	Validatiefouten in core-pagina’s.	Gebruik een expliciete `PageSize` wanneer het uitvoerformaat van belang is.
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	Lettertypefamilie, -stijl en puntgrootte.	Gebruikt een lege stijl en een grootte van 12 pt.	`static`	Fouten in het lettertyperegister of de codering.	Laad productielettertypen vooraf via `nextpdf.preload_fonts` wanneer latentie van belang is.
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	Celafmetingen, tekst, randvlag, regelafbrekingsvlag en uitlijning.	Gebruikt lege tekst, geen rand, geen regelafbreking en links uitlijnen.	`static`	Lay-out- of tekstcoderingsfouten.	Gebruik dit voor eenvoudige uitvoer met een vaste lay-out.
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	Celbreedte, regelhoogte, tekst, randvlag, uitlijning.	Geen rand en links uitlijnen.	`static`	Lay-out- of tekstcoderingsfouten.	Gebruik dit wanneer tekst binnen een vaste breedte moet afbreken.
`Pdf::writeHtml(string $html)`	`html`: HTML-fragment.	Rendert op de huidige pagina en maakt er een aan wanneer dat nodig is.	`static`	HTML-renderingfouten in de core.	Pas beleid voor invoergrootte en resources toe voordat je niet-vertrouwde HTML accepteert.
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	Bestandspad en optionele plaatsingsrechthoek.	Laat het core-document de huidige positie en de intrinsieke grootte kiezen wanneer coördinaten worden weggelaten.	`static`	Fouten bij beelddecodering, het pad of de lay-out.	Valideer het beleid voor de afbeeldingsbron voordat je door de gebruiker opgegeven paden accepteert.
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`: optionele naam; `dest`: uitvoerbestemming.	Geeft inline-uitvoer wanneer de bestemming wordt weggelaten.	`string`	Serialisatiefouten in de core.	Geef voor HTTP-responses in Laravel de voorkeur aan `PdfResponse`.
`Pdf::save(string $path)`	`path`: doel in het bestandssysteem.	Schrijft de voltooide PDF naar schijf.	`void`	Fouten in het bestandssysteem of bij het schrijven door de core.	Valideer uitvoermappen in de applicatiecode.
`Pdf::getPdfData()`	geen.	Materialiseert PDF-bytes in het geheugen.	`string`	Serialisatiefouten in de core.	Gebruik dit wanneer een ander framework-object eigenaar moet zijn van de responsebody.

Service provider en bindings

Gebruik deze tabel wanneer je een container-entry rechtstreeks moet omzetten of overschrijven, bijvoorbeeld wanneer je DocumentFactoryInterface in een service injecteert of wilt controleren wat provides() uitstelt.

Symbool	Parameters	Standaardgedrag	Retourneert	Genereert fout of mislukt met	Opmerkingen
`NextPdfServiceProvider::register()`	geen.	Voegt `config/nextpdf.php` samen; registreert registers, de documentfactory, de documentbinding, de HTTP-client, de TSA-client, de signer en optionele e-invoice-contracten.	`void`	Fouten in de container of bij het resolven van optionele klassen wanneer een functie wordt gebruikt.	`FontRegistryInterface` en `ImageRegistry` worden gedeeld; documenten zijn altijd vers.
`NextPdfServiceProvider::boot()`	geen.	Valideert vereiste PHP-extensies en publiceert `nextpdf-config` in console-modus.	`void`	`RuntimeException` als een vereiste extensie niet beschikbaar is.	Vereiste extensies zijn `mbstring` en `zlib`.
`NextPdfServiceProvider::provides()`	geen.	Rapporteert uitgestelde service-ID’s.	`array<string>`	geen verwacht.	Bevat `PdfDocumentInterface`, `DocumentFactoryInterface`, `FontRegistryInterface`, `SignerInterface`, `TsaClient`, `ClientInterface` en `nextpdf`.
`PdfDocumentInterface` / `nextpdf`	omgezet vanuit de Laravel-container.	Maakt via `DocumentFactoryInterface` een wegwerp-`Document` aan en past vervolgens geconfigureerde standaardwaarden en optionele PDF/A- of Artisan-instellingen toe.	`NextPDF\Core\Document`	Optionele extensiefouten wanneer geconfigureerd maar niet beschikbaar.	Laat de container voor elke request of job een nieuw document aanmaken.
`DocumentFactoryInterface`	omgezet vanuit de Laravel-container.	Singleton-factory die de font- en image-registers gedurende de levensduur van het proces deelt.	`DocumentFactoryInterface`	Fouten bij het initialiseren van het register.	Gebruik dit voor expliciete dependency injection.
`SignerInterface`	omgezet vanuit de Laravel-container.	Retourneert `null` tenzij `nextpdf.signature.enabled` is ingesteld en certificaatpaden zijn geconfigureerd.	`SignerInterface	null`	Fouten bij het laden van het certificaat of validatie op handtekeningniveau.

Configuratie

Gebruik deze tabel om de runtimegerichte nextpdf.*-sleutels op te zoeken die door de bindings worden gelezen. De volledige referentie per sleutel, inclusief omgevingsvariabelen en standaardwaarden, vind je op /integrations/laravel/configuration/.

Sleutel	Type	Standaardgedrag	Opmerkingen
`nextpdf.fonts_path`	`string`	Gebruikt lettertypen uit Laravel-resources wanneer weggelaten.	Map voor aangepaste lettertypen en warmup.
`nextpdf.cache_path`	`string`	Cachepad van de applicatie.	Houd het beschrijfbaar voor de PHP-worker.
`nextpdf.preload_fonts`	`list<string>`	Lege lijst.	Lettertypen worden vooraf opgewarmd tijdens het aanmaken van het register, waarna het register wordt vergrendeld.
`nextpdf.image_cache_mb`	`int`	Begrensde grootte van de afbeeldingscache.	Beperkt het geheugen van de afbeeldingscache gedurende de levensduur van het proces.
`nextpdf.defaults.*`	`array`	Maker is `NextPDF`, taal is `en`, plus optionele auteur- en lay-out-standaardwaarden.	Toegepast op elk vers document.
`nextpdf.artisan.*`	`array`	Chrome-renderer uitgeschakeld tenzij geïnstalleerd en geconfigureerd.	Verwijst naar `ChromeRendererConfig::fromArray()`.
`nextpdf.signature.*`	`array`	Ondertekening is standaard uitgeschakeld.	Certificaat, privésleutel, wachtwoord, extra certificaten en handtekeningniveau.
`nextpdf.tsa.*`	`array`	TSA is uitgeschakeld wanneer de Uniform Resource Locator (URL) leeg is.	Ondersteunt credentials, mutual Transport Layer Security-bestanden (mTLS), time-out, public-key-pins en HTTP-beleid.
`nextpdf.ocsp_cache.*`	`array`	Online Certificate Status Protocol-cache (OCSP) ingeschakeld met geconfigureerde TTL.	Gebruikt door validatieflows voor handtekeningen wanneer beschikbaar.

HTTP-responses

Gebruik deze tabel wanneer je een voltooid document via HTTP retourneert en moet kiezen tussen inline-weergave, attachment-download of streamingoutput.

Symbool	Parameters	Standaardgedrag	Retourneert	Genereert fout of mislukt met	Opmerkingen
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: opgebouwd document; `filename`: Content-Disposition-bestandsnaam.	Normaliseert lege bestandsnamen naar `document.pdf`.	`Illuminate\Http\Response`	Serialisatie- of responsopbouwfouten in de core.	Stelt het PDF-content-type en defensieve headers in.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Hetzelfde als `inline`; de dispositie is attachment.	Retourneert een downloadresponse voor de browser.	`Illuminate\Http\Response`	Hetzelfde als `inline`.	Gebruik dit voor expliciete bestandsdownloads.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Hetzelfde als `inline`.	Materialiseert PDF-bytes en zendt vervolgens chunks van 64 KB uit.	`Symfony\Component\HttpFoundation\StreamedResponse`	Hetzelfde als `inline`.	Dit is gestreamde HTTP-output, geen zero-copy-rendering.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Hetzelfde als `streamInline`; de dispositie is attachment.	Downloadstreamresponse.	`StreamedResponse`	Hetzelfde als `streamInline`.	Dwing limieten voor invoer- en uitvoergrootte af vóór het renderen.

Queue-job

Gebruik deze tabel wanneer je generatie buiten de request-thread om verplaatst. De tabel behandelt constructie, dispatch en callbacks bij succes of mislukken voor GeneratePdfJob.

Symbool	Parameters	Standaardgedrag	Retourneert	Genereert fout of mislukt met	Opmerkingen
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`: doel-`.pdf`; `builder`: ontvangt een `PdfDocumentInterface`; callbacks zijn optioneel.	Queuenaam, time-out en verbinding worden gelezen uit `config('nextpdf.queue.*')`.	Job-instantie.	Serialisatiefouten als de builder of callbacks niet serialiseerbaar zijn.	De builder moet het geconfigureerde document retourneren.
`GeneratePdfJob::handle()`	geen.	Zet `PdfDocumentInterface` om, past de builder toe, valideert het uitvoerpad en bewaart vervolgens.	`void`	`InvalidArgumentException` voor onveilige uitvoerpaden; schrijffouten in de core.	Weigert stream-wrappers, null-bytes, `..`-segmenten en niet-`.pdf`-paden.
`GeneratePdfJob::failed(Throwable $exception)`	`exception`: oorzaak van de mislukking.	Roept de geconfigureerde failure-callback aan wanneer die aanwezig is.	`void`	Callback-fouten.	Houd callbacks idempotent.
`GeneratePdfJob::then(callable $callback)`	`callback`: ontvangt het uitvoerpad.	Vervangt de success-callback.	`self`	Fouten met serialiseerbare closures.	Fluent helper voor dispatch-instelling.
`GeneratePdfJob::catch(callable $callback)`	`callback`: ontvangt de geworpen `Throwable`.	Vervangt de failure-callback.	`self`	Fouten met serialiseerbare closures.	Gebruik dit voor waarschuwingen of compenserende opschoning.

Ontwikkelnotities

PdfResponse roept altijd getPdfData() aan voordat het een response opbouwt. Het is geen luie documentbuilder.
Queue-payloads kunnen in gedeelde transports worden gemanipuleerd; beperk uitvoerpaden tot een map die door de applicatie wordt beheerd.
Gebruik een vers document per request of job. Hergebruik een document niet over requests heen.