NextPDF für CodeIgniter 4 konfigurieren

Auf einen Blick

Die Konfiguration liegt in NextPDF\CodeIgniter\Config\NextPdf, einer Unterklasse von CodeIgniters BaseConfig. Werte überschreiben Sie, indem Sie die Klasse in app/Config/ erweitern oder .env-Schlüssel mit dem Präfix nextpdf. setzen. Die Standardwerte funktionieren ohne weitere Konfiguration.

Konzeptioneller Überblick

NextPdf ist eine typisierte BaseConfig. Sie ist bewusst nicht final. Gemäß der CodeIgniter-Konvention erweitert die Anwendungskonfiguration die Paketklasse, damit die Anwendung die Standardwerte überschreiben kann. Beim Erzeugen der Konfiguration löst BaseConfig für jede öffentliche Eigenschaft die Umgebungs-Overrides auf. Diese Auflösung berücksichtigt auch verschachtelte Array-Schlüssel.

Die Standardpfade für Schriften und Cache verwenden die CodeIgniter-Konstante WRITEPATH: WRITEPATH . 'fonts' und WRITEPATH . 'cache/nextpdf'.

Konfigurationsschlüssel

Jeder unten aufgeführte Schlüssel ist eine öffentliche Eigenschaft von NextPdf. Die Standardwerte sind die verifizierten Werte aus dem Paketquellcode.

Standardwerte für Seite und Dokument

Schlüssel	Typ	Standard	Beschreibung
`pageFormat`	`string`	`A4`	Seitenformat.
`orientation`	`string`	`P`	`P` für Hochformat oder `L` für Querformat.
`unit`	`string`	`mm`	Maßeinheit.
`defaults.creator`	`string`	`NextPDF`	PDF-Creator-Metadaten.
`defaults.author`	`string`	`''`	Autor-Metadaten; werden bei leerem Wert übersprungen.
`defaults.language`	`string`	`en`	Sprach-Tag des Dokuments.
`defaults.margin_top`	`float`	`10.0`	Oberer Rand.
`defaults.margin_right`	`float`	`10.0`	Rechter Rand.
`defaults.margin_bottom`	`float`	`10.0`	Unterer Rand.
`defaults.margin_left`	`float`	`10.0`	Linker Rand.
`defaults.font_family`	`string`	`dejavusans`	Standardschriftfamilie.
`defaults.font_size`	`float`	`12.0`	Standardschriftgröße.
`defaults.trim_box`	`list<float>\|null`	`null`	Trim-Box, sofern gesetzt.
`defaults.bleed_box`	`list<float>\|null`	`null`	Bleed-Box, sofern gesetzt.

Das Paket wendet defaults.creator und defaults.language auf jedes Dokument an. defaults.author wird nur übernommen, wenn dieser Wert nicht leer ist.

Pfade und Caches

Schlüssel	Typ	Standard	Beschreibung
`fontsPath`	`string`	`WRITEPATH/fonts`	Verzeichnis für Schriftdateien.
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	Cache-Verzeichnis.
`preloadFonts`	`list<string>`	`[]`	Absolute Schriftpfade, die beim Booten vorgewärmt werden.
`imageCacheMb`	`int`	`50`	Budget des LRU-Bildcaches in MB.
`fontCacheLocking`	`bool`	`true`	Sperrt den Schriftcache nach dem Vorwärmen.

Die Schrift-Registry weist einen fontsPath zurück, der einen Stream-Wrapper (://) oder ein Null-Byte enthält. Die Zurückweisung löst einen Laufzeitfehler aus. Siehe /integrations/codeigniter/security-and-operations/.

Archivierung und Farbe (NextPDF Pro)

Schlüssel	Typ	Standard	Beschreibung
`pdfa`	`string\|null`	`null`	PDF/A-Version: `4`, `4e`, `4f`.
`iccProfile.rgb`	`string\|null`	`null`	Pfad zum RGB-ICC-Profil.
`iccProfile.cmyk`	`string\|null`	`null`	Pfad zum CMYK-ICC-Profil.

pdfa wird nur wirksam, wenn NextPDF Pro installiert ist und die Archivierungsfunktion verfügbar ist. Mit Core allein wird der Schlüssel ignoriert.

Digitale Signatur (NextPDF Pro / Enterprise)

Schlüssel	Typ	Standard	Beschreibung
`signature.enabled`	`bool`	`false`	Aktiviert den Signer-Dienst.
`signature.certificate`	`string\|null`	`null`	Pfad zur Zertifikatsdatei.
`signature.private_key`	`string\|null`	`null`	Pfad zur Datei des privaten Schlüssels.
`signature.password`	`string`	`''`	Passwort für den privaten Schlüssel.
`signature.extra_certs`	`list<string>`	`[]`	Pfade zu zusätzlichen Kettenzertifikaten.
`signature.level`	`string`	`B-B`	Bezeichner der Signaturstufe.

Services::pdfSigner() liefert null, wenn signature.enabled nicht true ist oder signature.certificate leer ist. Die Standardstufe ist B-B. NextPDF Pro stellt die B-B-Basissignatur bereit. Langfristige Validierungsstufen sind eine separate Enterprise-Fähigkeit. Sie sind in der Premium-Referenz dokumentiert, nicht hier.

PAdES B-T wird von der Core-Engine erzeugt. Die CodeIgniter-Integration fügt selbst kein B-T hinzu, und Pro liefert nur die B-B-Baseline. Diese Dokumentation wird aktualisiert, falls und sobald Pro B-T ausliefert.

Time Stamp Authority

Schlüssel	Typ	Standard	Beschreibung
`tsa.url`	`string\|null`	`null`	TSA-Endpunkt-URL.
`tsa.username`	`string`	`''`	TSA-Benutzername für Basic-Auth.
`tsa.password`	`string`	`''`	TSA-Passwort für Basic-Auth.
`tsa.cert`	`string\|null`	`null`	Pfad zum Client-Zertifikat.
`tsa.key`	`string\|null`	`null`	Pfad zum Client-Schlüssel.
`tsa.timeout`	`int`	`30`	Timeout für Anfragen in Sekunden.
`tsa.pinned_public_keys`	`list<string>`	`[]`	Gepinnte öffentliche TSA-Schlüssel.
`tsa.warn_on_key_rotation`	`bool`	`true`	Warnt bei TSA-Schlüsselrotation.
`tsa.allow_insecure_http`	`bool`	`false`	Erlaubt Klartext-HTTP zur TSA.

Services::tsaClient() liefert null, wenn tsa.url null oder ein leerer String ist. Wenn eine Signaturstufe ausgewählt ist, die einen Zeitstempel erfordert, bindet der Signer den TSA-Client automatisch ein.

OCSP-Cache

Schlüssel	Typ	Standard	Beschreibung
`ocspCache.enabled`	`bool`	`true`	Aktiviert den OCSP-Antwort-Cache.
`ocspCache.ttl`	`int`	`86400`	Cache-TTL in Sekunden.
`ocspCache.directory`	`string\|null`	`null`	Cache-Verzeichnis; bei null der Engine-Standard.

Chrome-HTML-Renderer (NextPDF Artisan)

Schlüssel	Typ	Standard	Beschreibung
`artisan.chrome_binary`	`string\|null`	`null`	Pfad zur Chrome-/Chromium-Binärdatei.
`artisan.render_timeout`	`int`	`30`	Render-Timeout in Sekunden.
`artisan.default_css`	`string`	`''`	Standard-Stylesheet.
`artisan.no_sandbox`	`bool`	`false`	Übergibt `--no-sandbox` an Chrome.
`artisan.max_html_size`	`int`	`5000000`	Maximale Größe des Eingabe-HTML in Bytes.

Der Chrome-Renderer wird nur auf dem Dokument konfiguriert, wenn artisan.chrome_binary gesetzt ist und nextpdf/artisan installiert ist.

Überschreiben mit `.env`

BaseConfig löst Umgebungs-Overrides pro Eigenschaft auf. Der Lookup-Schlüssel besteht aus dem kleingeschriebenen kurzen Klassennamen, nextpdf, gefolgt vom Eigenschaftspfad. Verschachtelte Array-Schlüssel werden über Punkte adressiert. Akzeptiert werden sowohl die Punkt- als auch die Unterstrichform.

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

Das Präfix ist der kleingeschriebene kurze Klassenname. Es bleibt nextpdf, obwohl die Klasse als NextPdf geschrieben wird. Die vollqualifizierte Form (NextPDF\CodeIgniter\Config\NextPdf.fontsPath) wird ebenfalls akzeptiert.

Durch Erweitern der Klasse überschreiben

Für eine typisierte, versionskontrollierte Konfiguration erweitern Sie die Paketklasse in app/Config/. CodeIgniter lädt die Anwendungsklasse statt des Paketstandards. Diese Datei deklariert eine Klasse und verursacht keine Seiteneffekte. Damit entspricht sie der PSR-1-Erwartung, dass eine Datei entweder Symbole deklariert oder seiteneffektbehaftete Logik ausführt, aber nicht beides (PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

Randfälle & Fallstricke

Wenn Sie einen einzelnen verschachtelten Schlüssel mit .env überschreiben, wird nur dieser Schlüssel überschrieben; der Rest des Arrays behält seinen Standard.
.env-Werte sind Strings. CodeIgniter wandelt true/false und numerische Strings um. Setzen Sie Werte in Anführungszeichen, wenn sie als literale Strings erhalten bleiben müssen.
Wenn Sie die Klasse mit einem partiellen defaults-Array erweitern, ersetzt das das gesamte Array. Nehmen Sie jeden Schlüssel auf, wie oben gezeigt.

Sicherheitshinweise

Halten Sie Zertifikats- und Schlüsselpfade aus der Versionsverwaltung heraus. Stellen Sie sie über .env oder einen Secrets-Manager bereit. tsa.allow_insecure_http muss in der Produktion false bleiben. Siehe /integrations/codeigniter/security-and-operations/.

Konformität

Die Datei zur Config-Erweiterung der Anwendung deklariert eine Klasse und verursacht keine Seiteneffekte (PSR-1 §x1.x1.p3).

Kommerzieller Kontext

NextPDF Core ist Apache-2.0. Die Signatur.*- und pdfa-Schlüssel werden nur wirksam, wenn NextPDF Pro oder Enterprise installiert ist. Das CodeIgniter-Paket stellt die entsprechenden Service-Methoden bereit. Diese Methoden liefern null, bis das passende Premium-Paket installiert ist. Siehe </get-license/?intent=codeigniter-signing>.

Siehe auch

/integrations/codeigniter/install/ — installiert das Paket.
/integrations/codeigniter/quickstart/ — erstes PDF erstellen.
/integrations/codeigniter/production-usage/ — Controller mit DI-Verdrahtung und Queue-Jobs.
/integrations/codeigniter/security-and-operations/ — Härtung der Signatur- und Pfadkonfiguration.