NextPDF Laravel-Boot und Auto-Discovery

Auf einen Blick

Laravel erkennt NextPdfServiceProvider automatisch über die composer.json des Pakets. Der Provider registriert verzögerte Container-Bindungen und veröffentlicht im Konsolenkontext die Konfigurationsdatei. Diese Seite erläutert den Discovery-Mechanismus und die Lebensdauer jeder Bindung.

Installation

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

Wie Laravel-Auto-Discovery funktioniert

Das Paket deklariert den Provider und den Facade-Alias in seiner eigenen composer.json im Block extra.laravel:

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

Wenn Sie composer require ausführen, liest Laravel diesen Block und registriert Provider und Alias. Sie müssen config/app.php oder bootstrap/providers.php nicht manuell bearbeiten. Das Array extra.laravel.providers registriert Service-Provider automatisch; extra.laravel.aliases registriert Facade-Aliase automatisch (Laravel 12 Package-Development-Leitfaden, https://laravel.com/docs/12.x/packages, abgerufen am 2026-05-18).

Boot-Sequenz

NextPdfServiceProvider implementiert sowohl DeferrableProvider als auch den regulären register()/boot()-Lebenszyklus.

register() führt die Paket-Konfiguration unter dem Schlüssel nextpdf zusammen. Anschließend bindet die Methode die Container-Einträge: Font-Registry, Image-Registry, Document-Factory, PSR-18-HTTP-Client, Timestamp-Client, Signer, Document und E-Invoice-Contracts. Jede Bindung ist eine Closure; daher wird hier nichts Aufwändiges konstruiert.
boot() prüft, ob die PHP-Erweiterungen mbstring und zlib geladen sind. Die Methode registriert die veröffentlichbare Konfiguration unter dem Tag nextpdf-config nur dann, wenn runningInConsole() true zurückgibt.

Der Provider ist verzögert; daher läuft register() erst, wenn Sie einen der von provides() zurückgegebenen Einträge auflösen. Das Auflösen eines nicht zugehörigen Container-Schlüssels bootet NextPDF nicht.

Container-Bindungen und Lebensdauern

PSR-11 erlaubt, dass zwei aufeinanderfolgende get()-Aufrufe mit demselben Identifier je nach Bindungsstrategie unterschiedliche Werte zurückgeben (PSR-11 §1.1.2). Der Provider nutzt das bewusst:

Bindungsschlüssel	Lebensdauer	Hinweise
`FontRegistryInterface` (+ Alias `FontRegistry`)	Singleton, nach dem Warmup gesperrt	Aus `preload_fonts` vorgewärmt; gesperrt, damit kein Request sie verändern kann
`ImageRegistry`	Singleton	Begrenzter LRU-Cache, über `image_cache_mb` dimensioniert; nicht gesperrt
`DocumentFactoryInterface` (+ Alias `DocumentFactory`)	Singleton	Zustandslos; nutzt die beiden Registries gemeinsam
`Psr\Http\Client\ClientInterface`	Singleton	Request-Forgery-bewusster Client, der einen Curl-Client kapselt; gebaut aus `tsa.*`
`TsaClient`	scoped	`null`, wenn `tsa.url` leer ist
`SignerInterface`	Factory	`null`, wenn das Signieren deaktiviert oder das Zertifikat leer ist
`PdfDocumentInterface` (+ Alias `nextpdf`)	Factory	Frisches `NextPDF\Core\Document` pro Auflösung, mit angewendeten Standardmetadaten
`EmbedderInterface`, `ValidatorInterface`, `ProfileInterface`, `SchematronRunnerInterface`	Factory	Werden zu Premium-Konkreta aufgelöst; Fehler beim ersten Auflösen ohne `nextpdf/premium`

Die Document-Bindung wendet defaults.creator, defaults.language und (sofern nicht leer) defaults.author auf jedes neu erzeugte Dokument an. Wenn pdfa nicht null ist, aktiviert sie PDF/A (Premium). Wenn der Abschnitt artisan vorhanden ist und eine Chrome-Browser-Factory-Klasse existiert, wendet sie die Chrome-Renderer-Konfiguration an.

has() des Containers nimmt einen einzelnen String-Identifier entgegen (PSR-11 §1.1.2). Die E-Invoice-Contracts sind gebunden; daher gibt has() für sie auch dann true zurück, wenn Premium fehlt. Das fehlende Konkretum schlägt erst bei der Konstruktion fehl.

Auto-Discovery deaktivieren

Fügen Sie das Paket dem dont-discover-Array der Anwendung hinzu und registrieren Sie den Provider anschließend manuell:

{
  "extra": {
    "laravel": {
      "dont-discover": ["nextpdf/laravel"]
    }
  }
}

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

Reihenfolge der Konfigurationsauflösung

Jeder Schlüssel wird in dieser Reihenfolge aufgelöst: Umgebungsvariable → veröffentlichter Wert aus config/nextpdf.php → Paket-Standard, der bei register() zusammengeführt wurde. Die meisten Schlüssel akzeptieren entweder einen NEXTPDF_*-Namen oder einen veralteten TCPDF_*-Umgebungsnamen. Verwenden Sie bevorzugt NEXTPDF_*.

Diagnose

php artisan package:discover --ansi

Eine Zeile, die nextpdf/laravel aufführt, bestätigt die Discovery. Da der Provider verzögert ist, erscheinen die Bindungen selbst erst bei der ersten Auflösung. Die Discovery-Zeile ist das korrekte Erfolgssignal.

Edge-Cases & Fallstricke

Die Registrierung zum Veröffentlichen der Konfiguration erfolgt nur im Konsolenkontext; ein reiner Web-Request löst sie daher nie aus. Führen Sie vendor:publish über die CLI aus.
Neben den Schlüsseln für Registry, Factory, HTTP-Client, Signer, Timestamp und Document umfasst provides() auch die vier E-Invoice-Contract-Schlüssel.
Eine frische Installation kann inaktiv wirken, bis erstmals ein relevanter Schlüssel aufgelöst wird. Das ist das beabsichtigte Verhalten des verzögerten Providers, kein Fehler.

Performance

register() ist O(1) — es werden nur Closures registriert. Das Aufwärmen der Font-Registry ist O(f) bezogen auf die vorab geladenen Fonts und läuft einmal pro Worker-Prozess. Die Verzögerung des Providers hält die Konstruktionskosten von NextPDF aus dem Boot-Pfad des Frameworks heraus, bis eine Bindung tatsächlich genutzt wird.

Sicherheitshinweise

Das verzögerte Design verkleinert die Angriffsfläche beim Booten. Die gesperrte Font-Registry verhindert in langlebigen Workern Request-übergreifende Mutationen des Font-Zustands. Die vollständige Bedrohungsabdeckung finden Sie unter /integrations/laravel/security-and-operations/.

Konformität

Aussage	Quelle	Klausel	reference_id
Aufeinanderfolgende Auflösungen können sich je nach Bindungsstrategie unterscheiden	PSR-11 Container	§1.1.2
`has()` nimmt einen einzelnen String-Identifier entgegen	PSR-11 Container	§1.1.2

Die Namen der Laravel-Discovery-Schlüssel wurden anhand der offiziellen Laravel 12 Paketdokumentation gegengeprüft (https://laravel.com/docs/12.x/packages, abgerufen am 2026-05-18).

Kommerzieller Kontext

Premium-Konkreta werden über dieselben verzögerten Bindungsschlüssel aufgelöst. Das ist eine optionale Enterprise-Funktion; das hier dokumentierte Core-Paket benötigt keine Codeänderung, um sie zu übernehmen. Siehe https://nextpdf.dev/get-license/?intent=laravel-signing.

Siehe auch

/integrations/laravel/install/ — Installation und Veröffentlichung
/integrations/laravel/overview/ — Paketarchitektur
/integrations/laravel/integration/ — End-to-End-Verdrahtungsanleitung
/integrations/laravel/configuration/ — alle Konfigurationsschlüssel