NextPDF configureren voor CodeIgniter 4

In een oogopslag

De NextPDF-configuratie bevindt zich in NextPDF\CodeIgniter\Config\NextPdf, een subklasse van de CodeIgniter-BaseConfig. Je kunt waarden overschrijven door de klasse uit te breiden in app/Config/ of door .env-sleutels in te stellen met het voorvoegsel nextpdf.. De standaardwaarden werken zonder extra configuratie.

Conceptueel overzicht

NextPdf is een getypeerde BaseConfig. De klasse is bewust niet final. In CodeIgniter breidt de applicatieconfiguratie de package-klasse uit, zodat je applicatie de standaardwaarden kan overschrijven. Wanneer CodeIgniter de configuratie opbouwt, past BaseConfig omgevingsoverschrijvingen toe op elke publieke eigenschap, inclusief geneste array-sleutels.

De standaardpaden voor lettertypen en de cache gebruiken de constante WRITEPATH van CodeIgniter: WRITEPATH . 'fonts' en WRITEPATH . 'cache/nextpdf'.

Configuratiesleutels

Elke sleutel hieronder is een publieke eigenschap van NextPdf. De standaardwaarden zijn geverifieerd aan de hand van de package-broncode.

Standaardwaarden voor pagina en document

Sleutel	Type	Standaard	Beschrijving
`pageFormat`	`string`	`A4`	Paginaformaat.
`orientation`	`string`	`P`	`P` voor staand of `L` voor liggend.
`unit`	`string`	`mm`	Maateenheid.
`defaults.creator`	`string`	`NextPDF`	Metadata voor de maker van het Portable Document Format (PDF).
`defaults.author`	`string`	`''`	Metadata voor de auteur; wordt overgeslagen wanneer leeg.
`defaults.language`	`string`	`en`	Taaltag van het document.
`defaults.margin_top`	`float`	`10.0`	Bovenmarge.
`defaults.margin_right`	`float`	`10.0`	Rechtermarge.
`defaults.margin_bottom`	`float`	`10.0`	Ondermarge.
`defaults.margin_left`	`float`	`10.0`	Linkermarge.
`defaults.font_family`	`string`	`dejavusans`	Standaardlettertypefamilie.
`defaults.font_size`	`float`	`12.0`	Standaardlettergrootte.
`defaults.trim_box`	`list<float>\|null`	`null`	Trim box, indien ingesteld.
`defaults.bleed_box`	`list<float>\|null`	`null`	Bleed box, indien ingesteld.

De package past defaults.creator en defaults.language toe op elk document. defaults.author wordt alleen toegepast wanneer de waarde niet leeg is.

Paden en caches

Sleutel	Type	Standaard	Beschrijving
`fontsPath`	`string`	`WRITEPATH/fonts`	Map met lettertypebestanden.
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	Cachemap.
`preloadFonts`	`list<string>`	`[]`	Absolute lettertypepaden die bij het opstarten vooraf worden geladen.
`imageCacheMb`	`int`	`50`	Budget voor de least-recently-used (LRU)-afbeeldingscache in megabytes (MB).
`fontCacheLocking`	`bool`	`true`	Vergrendelt de lettertypecache na het opwarmen.

Het lettertyperegister wijst elke fontsPath af die een stream wrapper (://) of een null-byte bevat, en geeft een runtimefout. Zie /integrations/codeigniter/security-and-operations/.

Archivering en kleur (NextPDF Pro)

Sleutel	Type	Standaard	Beschrijving
`pdfa`	`string\|null`	`null`	PDF/A-versie: `4`, `4e`, `4f`.
`iccProfile.rgb`	`string\|null`	`null`	Pad naar het International Color Consortium (ICC)-profiel voor rood, groen en blauw (RGB).
`iccProfile.cmyk`	`string\|null`	`null`	Pad naar het International Color Consortium (ICC)-profiel voor cyaan, magenta, geel en zwart (CMYK).

pdfa is alleen van kracht wanneer NextPDF Pro is geïnstalleerd en de archiveringscapaciteit beschikbaar is. Wanneer je alleen core gebruikt, wordt de sleutel genegeerd.

Digitale handtekening (NextPDF Pro / Enterprise)

Sleutel	Type	Standaard	Beschrijving
`signature.enabled`	`bool`	`false`	Schakelt de ondertekeningsservice in.
`signature.certificate`	`string\|null`	`null`	Pad naar het certificaatbestand.
`signature.private_key`	`string\|null`	`null`	Pad naar het privésleutelbestand.
`signature.password`	`string`	`''`	Wachtwoord voor de privésleutel.
`signature.extra_certs`	`list<string>`	`[]`	Paden naar aanvullende ketencertificaten.
`signature.level`	`string`	`B-B`	Identifier van het handtekeningniveau.

Services::pdfSigner() retourneert null tenzij signature.enabled true is en signature.certificate niet leeg is. Het standaardniveau is B-B. NextPDF Pro levert de B-B-basishandtekening. Niveaus voor langetermijn- validatie zijn een afzonderlijke Enterprise-functionaliteit en zijn gedocumenteerd in de Premium-referentie, niet hier.

PDF Advanced Electronic Signatures (PAdES) B-T wordt geproduceerd door de Core- engine. De CodeIgniter-integratie voegt zelf geen B-T toe, en Pro levert uitsluitend de B-B-basis. Deze documentatie wordt bijgewerkt als en wanneer Pro B-T uitbrengt.

Time Stamp Authority

Sleutel	Type	Standaard	Beschrijving
`tsa.url`	`string\|null`	`null`	Endpoint-URL van de Time Stamp Authority (TSA).
`tsa.username`	`string`	`''`	Gebruikersnaam voor TSA-basisauthenticatie.
`tsa.password`	`string`	`''`	Wachtwoord voor TSA-basisauthenticatie.
`tsa.cert`	`string\|null`	`null`	Pad naar het clientcertificaat.
`tsa.key`	`string\|null`	`null`	Pad naar de clientsleutel.
`tsa.timeout`	`int`	`30`	Time-out van het verzoek in seconden.
`tsa.pinned_public_keys`	`list<string>`	`[]`	Gepinde publieke TSA-sleutels.
`tsa.warn_on_key_rotation`	`bool`	`true`	Waarschuwt bij rotatie van de TSA-sleutel.
`tsa.allow_insecure_http`	`bool`	`false`	Staat HTTP in platte tekst naar de TSA toe.

Services::tsaClient() retourneert null wanneer tsa.url null of een lege tekenreeks is. Wanneer je een handtekeningniveau selecteert dat een tijdstempel vereist, koppelt de ondertekenaar automatisch de TSA-client.

OCSP-cache

Sleutel	Type	Standaard	Beschrijving
`ocspCache.enabled`	`bool`	`true`	Schakelt de responscache van het Online Certificate Status Protocol (OCSP) in.
`ocspCache.ttl`	`int`	`86400`	Time to live (TTL) van de cache in seconden.
`ocspCache.directory`	`string\|null`	`null`	Cachemap; gebruikt de standaard van de engine wanneer null.

Chrome-HTML-weergave-engine (NextPDF Artisan)

Sleutel	Type	Standaard	Beschrijving
`artisan.chrome_binary`	`string\|null`	`null`	Pad naar het Chrome/Chromium-binaire bestand.
`artisan.render_timeout`	`int`	`30`	Time-out van de weergave in seconden.
`artisan.default_css`	`string`	`''`	Standaardstijlblad.
`artisan.no_sandbox`	`bool`	`false`	Geeft `--no-sandbox` door aan Chrome.
`artisan.max_html_size`	`int`	`5000000`	Maximale grootte van de invoer-HTML in bytes.

De Chrome-weergave-engine wordt alleen voor het document ingesteld wanneer artisan.chrome_binary is ingesteld en nextpdf/artisan is geïnstalleerd.

Overschrijven met `.env`

BaseConfig verwerkt omgevingsoverschrijvingen per eigenschap. De opzoeksleutel is de korte klassenaam in kleine letters, nextpdf, gevolgd door het eigenschapspad. Gebruik punten om geneste array-sleutels te adresseren. Zowel punt- als underscore-notatie worden geaccepteerd.

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

Het voorvoegsel is de korte klassenaam in kleine letters. Het blijft nextpdf ook als de klasse wordt geschreven als NextPdf. Je kunt ook de volledig gekwalificeerde vorm gebruiken (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Overschrijven door de klasse uit te breiden

Voor getypeerde, versiebeheerde configuratie breid je de package-klasse uit in app/Config/. CodeIgniter laadt de applicatieklasse in plaats van de package-standaard. Dit bestand declareert een klasse en heeft geen neveneffecten. Daarmee blijft het in lijn met de PSR-1-verwachting dat een bestand ofwel symbolen declareert ofwel logica met neveneffecten uitvoert, maar niet beide (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,
    ];
}

Randgevallen en valkuilen

Het overschrijven van één geneste sleutel met .env wijzigt alleen die sleutel; de rest van de array behoudt de standaardwaarde.
.env-waarden zijn tekenreeksen. CodeIgniter cast true/false en numerieke tekenreeksen. Zet waarden tussen aanhalingstekens als ze letterlijke tekenreeksen moeten blijven.
Het uitbreiden van de klasse met een gedeeltelijke defaults-array vervangt de volledige array. Neem elke sleutel op, zoals hierboven getoond.

Beveiligingsnotities

Houd certificaat- en sleutelpaden buiten broncodebeheer. Lever ze aan via .env of een secrets manager. tsa.allow_insecure_http moet in productie false blijven. Zie /integrations/codeigniter/security-and-operations/.

Conformiteit

Het configuratie-uitbreidingsbestand van de applicatie declareert één klasse en heeft geen neveneffecten (PSR-1 §x1.x1.p3).

Commerciële context

NextPDF core is Apache-2.0. Sleutels signature.* en pdfa zijn alleen van kracht wanneer NextPDF Pro of Enterprise is geïnstalleerd. De CodeIgniter-package stelt de bijbehorende servicemethoden beschikbaar. Die methoden retourneren null totdat je de bijbehorende Premium-package installeert. Zie </get-license/?intent=codeigniter-signing>.

Zie ook

/integrations/codeigniter/install/ — de package installeren.
/integrations/codeigniter/quickstart/ — je eerste PDF.
/integrations/codeigniter/production-usage/ — DI-bedrade controllers en wachtrijtaken.
/integrations/codeigniter/security-and-operations/ — hardening van de ondertekenings- en padconfiguratie.