NextPDF-Laravel-Paket konfigurieren

Auf einen Blick

config/nextpdf.php wird mit php artisan vendor:publish --tag=nextpdf-config veröffentlicht. Jeder Schlüssel hat einen Fallback über eine Umgebungsvariable und einen fest codierten Standardwert. Diese Seite dokumentiert jeden Schlüssel exakt so, wie er in der config/nextpdf.php des Pakets steht.

Installation

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

Der Provider führt während register() außerdem die Paketstandards unter dem Konfigurationsschlüssel nextpdf zusammen. Nicht gesetzte Schlüssel greifen daher bereits vor dem Veröffentlichen auf die unten stehenden Werte zurück.

Konzeptioneller Überblick

Die meisten Umgebungsvariablen akzeptieren entweder einen NEXTPDF_*-Namen oder einen veralteten TCPDF_*-Namen. Das veraltete Präfix wird während des in UPGRADE.md dokumentierten Übergangszeitraums unterstützt; neue Deployments sollten die Schreibweise NEXTPDF_* verwenden. Die Konfigurationsdatei löst Werte in dieser Reihenfolge auf: Umgebungsvariable → veröffentlichter Dateiwert → Paketstandard.

API-Oberfläche — Konfigurationsschlüssel

Dokumentlayout

Schlüssel	Env (primär)	Standard	Wirkung
page_format	NEXTPDF_PAGE_FORMAT	A4	Standardseitenformat (A4, A3, A5, Letter, Legal, Tabloid)
orientation	NEXTPDF_ORIENTATION	P	Hochformat (P) oder Querformat (L)
unit	NEXTPDF_UNIT	mm	Maßeinheit (pt, mm, cm, in)
defaults.creator	NEXTPDF_CREATOR	NextPDF	Metadaten zum Dokumentersteller; werden auf die PdfDocumentInterface-Bindung angewendet
defaults.author	NEXTPDF_AUTHOR	(leer)	Autorenmetadaten; werden nur angewendet, wenn sie nicht leer sind
defaults.language	NEXTPDF_LANG	en	Dokumentsprache; angewendet auf die Dokumentbindung
defaults.margin_top / _right / _bottom / _left	—	10	Standardränder
defaults.font_family	—	dejavusans	Standardschriftfamilie
defaults.font_size	—	12	Standardschriftgröße
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] in Punkten oder null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] in Punkten oder null

Der Provider wendet defaults.creator, defaults.language und (falls gesetzt) defaults.author auf jedes neu aufgelöste Dokument an. Der Zweig defaults.author wird übersprungen, wenn der Wert leer ist.

Archivierung und Farbe

Schlüssel	Env (primär)	Standard	Wirkung
pdfa	NEXTPDF_PDFA	null	PDF/A-Archivierungsstufe (null, 4, 4e, 4f). Ein Wert ungleich null aktiviert PDF/A auf der Dokumentbindung und erfordert nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Verzeichnis für zusätzliche TrueType-Schriften; steuert den Suchpfad der Schriftregistrierung
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Cache-Verzeichnis für geparste Schriften und temporäre Dateien
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Pfad zum RGB-ICC-Profil; erforderlich für PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Optionales CMYK-ICC-Profil für Druckworkflows
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Verwendet flock für den Schrift-Cache, um Beschädigungen zu verhindern, wenn mehrere Queue-Worker parallel schreiben

Wird pdfa auf einen Wert ungleich null gesetzt, ist die Premium-Stufe erforderlich. Ohne nextpdf/premium löst das Auflösen der Dokumentbindung mit gesetztem pdfa einen Class-not-found-Fehler für den PDF/A-Versionstyp aus. Diese Seite beschreibt das Premium-Archivierungsverhalten nicht; siehe die Premium- Dokumentation.

Worker-Speicher (langlebige Laufzeiten)

Schlüssel	Env (primär)	Standard	Wirkung
preload_fonts	—	[]	Liste absoluter Schriftdateipfade, die beim Worker-Start geparst werden. Die Schriftregistrierung wird nach dem Warm-up gesperrt
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	LRU-Image-Cache-Budget in MB. 0 deaktiviert das Caching. Auf Provider-Ebene wird keine Obergrenze erzwungen

Das Image-Cache-Budget hat keine vom Provider erzwungene Obergrenze. Wenden Sie ein Speicherlimit auf Container-Ebene oder php.inimemory_limit an, um es zu begrenzen. Die Konfigurationsdatei empfiehlt ein praktisches Maximum von 256 MB.

Digitale Signatur (Premium)

Schlüssel	Env (primär)	Standard	Wirkung
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Bei false (oder leerem Zertifikat) ergibt sich für SignerInterface der Wert null
signature.certificate	NEXTPDF_SIGN_CERT	null	Pfad zum Signaturzertifikat
signature.private_key	NEXTPDF_SIGN_KEY	null	Pfad zum privaten Schlüssel
signature.password	NEXTPDF_SIGN_PASSWORD	(leer)	Schlüssel-Passphrase
signature.extra_certs	—	[]	Pfade zu Zwischen-CA-Zertifikaten
signature.level	NEXTPDF_SIGN_LEVEL	B-B	PAdES-Baseline-Stufe, die an den Signierer übergeben wird

Das hier dokumentierte Core-Paket liefert keine konkrete Signierer-Implementierung; die Bindung SignerInterface löst zu null auf, bis nextpdf/premium einen Signierer bereitstellt. Mit Premium erzeugt level: B-B eine PAdES-B-B-Baseline-Signatur. Höhere PAdES-Baselines hängen von einer konfigurierten Zeitstempelstelle und den Premium-Fähigkeiten ab; diese Seite dokumentiert jene Stufen nicht.

Zeitstempelstelle

Schlüssel	Env (primär)	Standard	Wirkung
tsa.url	NEXTPDF_TSA_URL	null	TSA-Endpunkt. Bei leerem Wert ergibt sich für TsaClient der Wert null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(leer)	HTTP-Anmeldedaten für die TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Client-Zertifikat/-Schlüssel für mTLS zur TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	HTTP-Timeout in Sekunden für den PSR-18-Client
tsa.pinned_public_keys	—	[]	Base64-SHA-256-SPKI-Pins (RFC 7469). Leer deaktiviert das Pinning
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Gibt eine Warnung aus, wenn die TSA ein nicht gepinntes SPKI präsentiert
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Erlaubt Klartext-HTTP zur TSA. In der Produktion auf false belassen

OCSP-Antwort-Cache

Schlüssel	Env (primär)	Standard	Wirkung
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Speichert OCSP-Antworten während der Validierung im Cache
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	Cache-TTL in Sekunden
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Cache-Verzeichnis; null hält den Cache nur im Arbeitsspeicher

Queue

Schlüssel	Env (primär)	Standard	Wirkung
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Queue-Verbindung; null nutzt die Standardverbindung
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Queue-Name, in die GeneratePdfJob gestellt wird
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Timeout pro Job in Sekunden

Chrome-CDP-Renderer (Artisan-Erweiterung)

Schlüssel	Env (primär)	Standard	Wirkung
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	Env-Wert oder nicht gesetzt	Pfad zur Chrome-/Chromium-Binärdatei
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Render-Timeout in Sekunden
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(leer)	Standard-CSS, das in gerendertes HTML injiziert wird
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Deaktiviert die Chrome-Sandbox
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Maximale HTML-Eingabegröße in Bytes

Der Abschnitt artisan wird nur dann auf die Dokumentbindung angewendet, wenn eine Chrome-Browser-Factory-Klasse vorhanden ist (die nextpdf/artisan-Erweiterung). Ist sie nicht vorhanden, wird der Abschnitt ignoriert.

Codebeispiel — Produktion

resource: config/nextpdf.php (subset, verified against the published file)

<?php

declare(strict_types=1);

return [
    'page_format'     => env('NEXTPDF_PAGE_FORMAT', 'A4'),
    'orientation'     => env('NEXTPDF_ORIENTATION', 'P'),
    'unit'            => env('NEXTPDF_UNIT', 'mm'),
    'pdfa'            => env('NEXTPDF_PDFA', null),
    'fonts_path'      => env('NEXTPDF_FONTS_PATH', resource_path('fonts')),
    'preload_fonts'   => [],
    'image_cache_mb'  => env('NEXTPDF_IMAGE_CACHE_MB', 50),
    'queue' => [
        'connection' => env('NEXTPDF_QUEUE_CONNECTION', null),
        'queue'      => env('NEXTPDF_QUEUE_NAME', 'pdf'),
        'timeout'    => env('NEXTPDF_QUEUE_TIMEOUT', 120),
    ],
];

Randfälle & Stolpersteine

• signature.enabled = true mit leerem signature.certificate löst SignerInterface dennoch zu null auf; beide müssen gesetzt sein.
• tsa.url = null erzwingt TsaClient zu null, selbst wenn andere tsa.*-Schlüssel befüllt sind.
• signature.level = null fällt beim Signierer auf PAdES B-B zurück.
• image_cache_mb auf null (nicht 0) gesetzt, fällt auf den Standard von 50 MB zurück; 0 deaktiviert das Caching ausdrücklich.
• Veraltete TCPDF_*-Umgebungsvariablen bleiben lesbar, sind aber veraltet; migrieren Sie zu NEXTPDF_*.

Performance

Das Lesen der Konfiguration ist ein O(1)-Array-Zugriff. preload_fonts tauscht einen einmaligen O(f)-Parse beim Worker-Start gegen geringere Latenz bei der ersten Anfrage. Ein größeres image_cache_mb reduziert wiederholtes Bilddecodieren auf Kosten von prozessresidentem Arbeitsspeicher.

Sicherheitshinweise

tsa.allow_insecure_http schwächt das Vertrauen in Zeitstempel und muss in der Produktion false bleiben. TSA-URLs sollten ausschließlich aus vertrauenswürdiger Konfiguration stammen; werden sie über eine Admin-Oberfläche zugänglich gemacht, wenden Sie eine Egress-Firewall- oder DNS-Richtlinie an, um Request-Forgery zu entschärfen. Siehe /integrations/laravel/security-and-operations/.

Konformität

Kein normativer Standard regelt die Form der Konfigurationsdatei; alle Schlüssel werden gegen die config/nextpdf.php des Pakets in der dokumentierten Revision verifiziert. Die Semantik der Signaturstufen wird von Premium geregelt und liegt außerhalb des Umfangs dieser Core-Seite.

Kommerzieller Kontext

Die Abschnitte signature und tsa steuern das Premium-Signieren, 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/install/ — die Konfigurationsdatei veröffentlichen
• /integrations/laravel/production-usage/ — Konfiguration in einem echten Controller anwenden
• /integrations/laravel/security-and-operations/ — Härtung der TSA- und Queue-Einstellungen
• /integrations/laravel/boot-and-discovery/ — welche Bindung jeder Schlüssel steuert