NextPDF-Integration in Laravel

Auf einen Blick

In dieser Anleitung binden Sie NextPDF in eine Laravel-12-Anwendung ein. Sie durchlaufen sechs Schritte: Sie installieren das Paket, lassen es von Laravel automatisch erkennen, veröffentlichen die Konfiguration, lösen die Container-Bindungen auf, geben eine HTTP-Response zurück und führen einen gestaffelten Job aus. Jeder Schritt verweist auf die ausführliche Referenz für den jeweiligen Bereich.

Installation

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

Boot/Auto-Discovery

Laravel erkennt den Service-Provider und den Facade-Alias automatisch aus dem composer.jsonextra.laravel-Block des Pakets. Sie müssen config/app.php nicht bearbeiten. Die Autoload-Map ist ein einzelner PSR-4-Eintrag. Das Präfix NextPDF\Laravel\ wird gemäß der PSR-4-Regel zur Abbildung von Präfix auf Basisverzeichnis (PSR-4 §3) zu src/Laravel/ aufgelöst. Der Provider ist aufgeschoben (deferred). Er bootet, sobald einer seiner provides()-Einträge zum ersten Mal aufgelöst wird. Die vollständigen Discovery-Interna finden Sie unter /integrations/laravel/boot-and-discovery/.

Container-Bindungen

Lösen Sie den Dokument-Contract aus dem Container auf. Ein gebundener Identifier wird zu seinem registrierten Eintrag aufgelöst (PSR-11 §1.1.2). Die Dokument-Bindung ist eine Factory, sodass jede Auflösung ein frisches Dokument liefert. Die Font- und Image-Registries sind Singletons, sodass jede Auflösung dieselbe gemeinsam genutzte Instanz zurückgibt. Die vollständige Tabelle der Bindungs-Lebensdauern finden Sie unter /integrations/laravel/overview/ und /integrations/laravel/boot-and-discovery/.

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

Konfiguration veröffentlichen

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

Dieser Befehl schreibt config/nextpdf.php. Jeder Schlüssel, seine Umgebungsvariable und sein Standardwert sind unter /integrations/laravel/configuration/ dokumentiert.

Smoke-Test für Service-Provider/Bundle

Das Paket enthält eine Testbench-basierte Test-Suite, die den Provider durchgängig durchläuft. Hier ist ein minimaler Smoke-Test, den Sie einer konsumierenden Anwendung hinzufügen können:

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

Diese beiden Assertions entsprechen den Use-once-Konformitätsprüfungen im paketeigenen EInvoiceServiceProviderIntegrationTest. Sie bestätigen, dass das Dokument als Factory gebunden ist und dass die Font-Registry als gesperrtes Singleton vorliegt.

Öffentliche API-Einstiegspunkte

Einstiegspunkt	Zweck	Referenz
`NextPDF\Laravel\Facades\Pdf`	Statischer Proxy zu einem frischen Dokument	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Container-aufgelöstes Dokument	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Inline-/Download-/gestreamte HTTP-Responses	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Gestaffelte Generierung	/integrations/laravel/production-usage/

Code-Beispiel — Production

Der über Dependency Injection verdrahtete und mit Fehlerbehandlung versehene Controller ist unter /integrations/laravel/production-usage/ vollständig dokumentiert. Dasselbe gilt für den gestaffelten Job mit seinen Erfolgs- und Fehler-Callbacks.

Edge Cases & Stolperfallen

Lösen Sie PdfDocumentInterface auf, nicht das konkrete Document. So bleibt die Bindung testbar und austauschbar.
SignerInterface und TsaClient werden zu null aufgelöst, bis sie konfiguriert sind. Prüfen Sie immer auf null.
Die E-Invoice-Contracts setzen nextpdf/premium voraus. Sie sind gebunden, schlagen aber ohne dieses Paket bei der ersten Auflösung fehl.

Performance

Die durchgängige Verdrahtung verursacht keine Boot-Kosten, da der Provider aufgeschoben ist. Die Kosten für die Konstruktion bei der ersten Auflösung und für das Font-Warmup werden unter /integrations/laravel/boot-and-discovery/ behandelt.

Sicherheitshinweise

PdfResponse wendet einen festen Satz von OWASP-Headern an. GeneratePdfJob validiert seinen Ausgabepfad auf dem Worker. Das Bedrohungsmodell finden Sie unter /integrations/laravel/security-and-operations/.

Konformität

Aussage	Quelle	Klausel	reference_id
Gebundener Identifier wird zu seinem registrierten Eintrag aufgelöst	PSR-11 Container	§1.1.2
PSR-4-Präfix wird auf Basisverzeichnis abgebildet	PSR-4 Autoloader	§3

Kommerzieller Kontext

Signing-, PDF/A- und E-Invoice-Contracts werden über denselben Provider integriert, wenn nextpdf/premium installiert ist. Dies ist eine optionale Enterprise-Fähigkeit. Das hier dokumentierte Core-Paket erfordert keine Code-Änderung, um sie zu übernehmen. Siehe https://nextpdf.dev/get-license/?intent=laravel-signing.

Siehe auch

/integrations/laravel/overview/ — Architektur und Bindungstabelle
/integrations/laravel/install/ — Installation und optionale Erweiterungen
/integrations/laravel/quickstart/ — erstes lauffähiges Beispiel
/integrations/laravel/production-usage/ — DI, Fehlerbehandlung, Queue
/integrations/laravel/boot-and-discovery/ — Discovery und Lebensdauern