NextPDF Laravel-integratie

In een oogopslag

Deze how-to helpt je NextPDF in te stellen binnen een Laravel 12-applicatie. Je doorloopt zes fasen: het package installeren, Laravel het automatisch laten detecteren, de configuratie publiceren, de containerbindings resolven, een Hypertext Transfer Protocol (HTTP)-response retourneren en een job in de wachtrij uitvoeren. Elke fase verwijst naar de uitgebreide referentie over dat onderwerp.

Installeren

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

Boot/auto-discovery

Laravel detecteert de service provider en de facade-alias automatisch vanuit het composer.jsonextra.laravel-blok van het package. Je hoeft config/app.php niet te bewerken. De autoload-map gebruikt één PSR-4-entry. De prefix NextPDF\Laravel\ wordt gekoppeld aan src/Laravel/ volgens de PSR-4-regel die een prefix aan een basismap koppelt (PSR-4 §3). Omdat de provider deferred is, boot hij pas wanneer een van de provides()-entries voor het eerst wordt geresolved. Zie /integrations/laravel/boot-and-discovery/ voor de volledige interne werking van discovery.

Containerbindings

Resolve het documentcontract via de container. Een gebonden identifier wordt geresolved naar de bijbehorende geregistreerde entry (PSR-11 §1.1.2). De documentbinding is een factory, dus elke resolve retourneert een vers document. De lettertype- en afbeeldingsregistries zijn singletons, dus elke resolve retourneert dezelfde gedeelde instantie. Zie /integrations/laravel/overview/ en /integrations/laravel/boot-and-discovery/ voor de volledige tabel met binding-lifetimes.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

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

Configuratie publiceren

php artisan vendor:publish --tag=nextpdf-config

Dit commando schrijft config/nextpdf.php. De configuratiereferentie in /integrations/laravel/configuration/ beschrijft elke sleutel, de bijbehorende omgevingsvariabele en de standaardwaarde.

Smoke-test voor service provider/bundle

Het package bevat een op Testbench gebaseerde testsuite die de provider volledig doorloopt. Voeg deze minimale smoke-test toe aan een applicatie die het package gebruikt:

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

Deze twee assertions komen overeen met de use-once-conformiteitscontroles van het package in EInvoiceServiceProviderIntegrationTest. Ze bevestigen dat het document factory-bound is en dat de lettertyperegistry een vergrendelde singleton is.

Publieke API-entry points

Entry point	Doel	Referentie
`NextPDF\Laravel\Facades\Pdf`	Statische proxy naar een vers document	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Via de container geresolved document	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Inline-, download- en gestreamde HTTP-responses	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Generatie in de wachtrij	/integrations/laravel/production-usage/

Codevoorbeeld — Productie

De volledige controller in /integrations/laravel/production-usage/ toont dependency injection en error handling. Dezelfde pagina behandelt ook de job in de wachtrij en de bijbehorende success- en failure-callbacks.

Randgevallen en valkuilen

Resolve PdfDocumentInterface, niet het concrete Document, zodat de binding testbaar en verwisselbaar blijft.
SignerInterface en TsaClient resolven naar null totdat ze geconfigureerd zijn. Controleer daarom altijd op null.
De e-invoicecontracten vereisen nextpdf/premium. Ze zijn wel gebonden, maar zonder dit package geven ze bij de eerste resolve een fout.

Performance

De end-to-end wiring veroorzaakt geen bootkosten, omdat de provider deferred is. De constructiekosten bij de eerste resolve en de warmup-kosten voor lettertypen worden behandeld in /integrations/laravel/boot-and-discovery/.

Beveiligingsnotities

PdfResponse past een vaste set Open Worldwide Application Security Project (OWASP)-headers toe. GeneratePdfJob valideert het uitvoerpad op de worker. Zie /integrations/laravel/security-and-operations/ voor het threat model.

Conformiteit

Bewering	Bron	Clausule	reference_id
Gebonden identifier resolvet naar zijn geregistreerde entry	PSR-11 Container	§1.1.2
PSR-4-prefix wordt toegewezen aan de basismap	PSR-4 Autoloader	§3

Commerciële context

Wanneer nextpdf/premium is geïnstalleerd, integreren de contracten voor ondertekening, PDF/A en e-invoice via dezelfde provider. Voor het hier gedocumenteerde Core-package is geen codewijziging nodig om deze optionele Enterprise-functionaliteit over te nemen. Zie https://nextpdf.dev/get-license/?intent=laravel-signing.

Zie ook

/integrations/laravel/overview/ — architectuur en bindingstabel
/integrations/laravel/install/ — installatie en optionele extensies
/integrations/laravel/quickstart/ — eerste uitvoerbare voorbeeld
/integrations/laravel/production-usage/ — dependency injection, error handling en wachtrij
/integrations/laravel/boot-and-discovery/ — discovery en lifetimes