Konfiguracja NextPDF dla CodeIgniter 4

W skrócie

Konfiguracja NextPDF znajduje się w klasie NextPDF\CodeIgniter\Config\NextPdf, podklasie BaseConfig z CodeIgniter. Wartości można nadpisać przez rozszerzenie klasy w katalogu app/Config/ albo ustawienie kluczy .env z przedrostkiem nextpdf. Wartości domyślne działają bez dodatkowej konfiguracji.

Przegląd koncepcyjny

NextPdf to typowana klasa BaseConfig. Celowo nie jest oznaczona jako final. W CodeIgniter konfiguracja aplikacji rozszerza klasę pakietu, dzięki czemu aplikacja może nadpisać wartości domyślne. Gdy CodeIgniter tworzy konfigurację, BaseConfig rozwiązuje nadpisania środowiskowe dla każdej właściwości publicznej, również dla zagnieżdżonych kluczy tablic.

Domyślne ścieżki czcionek i pamięci podręcznej korzystają ze stałej WRITEPATH CodeIgniter: WRITEPATH . 'fonts' oraz WRITEPATH . 'cache/nextpdf'.

Klucze konfiguracji

Każdy z poniższych kluczy jest właściwością publiczną klasy NextPdf. Wartości domyślne zweryfikowano względem źródła pakietu.

Wartości domyślne strony i dokumentu

Klucz	Typ	Domyślna	Opis
pageFormat	string	A4	Format strony.
orientation	string	P	P orientacja pionowa lub L pozioma.
unit	string	mm	Jednostka miary.
defaults.creator	string	NextPDF	Metadane twórcy formatu Portable Document Format (PDF).
defaults.author	string	''	Metadane autora; pomijane, gdy puste.
defaults.language	string	en	Znacznik języka dokumentu.
defaults.margin_top	float	10.0	Margines górny.
defaults.margin_right	float	10.0	Margines prawy.
defaults.margin_bottom	float	10.0	Margines dolny.
defaults.margin_left	float	10.0	Margines lewy.
defaults.font_family	string	dejavusans	Domyślna rodzina czcionek.
defaults.font_size	float	12.0	Domyślny rozmiar czcionki.
defaults.trim_box	list<float>|null	null	Ramka przycięcia (trim box), jeśli ustawiona.
defaults.bleed_box	list<float>|null	null	Ramka spadu (bleed box), jeśli ustawiona.

Pakiet stosuje defaults.creator oraz defaults.language w każdym dokumencie. Klucz defaults.author stosuje tylko wtedy, gdy wartość jest niepusta.

Ścieżki i pamięć podręczna

Klucz	Typ	Domyślna	Opis
fontsPath	string	WRITEPATH/fonts	Katalog plików czcionek.
cachePath	string	WRITEPATH/cache/nextpdf	Katalog pamięci podręcznej.
preloadFonts	list<string>	[]	Bezwzględne ścieżki czcionek wczytywanych wstępnie przy starcie.
imageCacheMb	int	50	Budżet pamięci podręcznej obrazów w megabajtach (MB), zarządzanej algorytmem least recently used (LRU).
fontCacheLocking	bool	true	Blokowanie pamięci podręcznej czcionek po jej rozgrzaniu.

Rejestr czcionek odrzuca każdą ścieżkę fontsPath, która zawiera opakowanie strumienia (://) lub bajt zerowy, i zgłasza błąd wykonania. Zobacz /integrations/codeigniter/security-and-operations/.

Archiwizacja i kolor (NextPDF Pro)

Klucz	Typ	Domyślna	Opis
pdfa	string|null	null	Wersja PDF/A: 4, 4e, 4f.
iccProfile.rgb	string|null	null	Ścieżka profilu International Color Consortium (ICC) dla przestrzeni barw czerwień, zieleń i niebieski (RGB).
iccProfile.cmyk	string|null	null	Ścieżka profilu ICC dla przestrzeni barw cyjan, magenta, żółty i kluczowy (CMYK).

pdfa działa tylko wtedy, gdy zainstalowano NextPDF Pro i dostępna jest funkcja archiwizacji. W samym rdzeniu klucz jest ignorowany.

Podpis cyfrowy (NextPDF Pro / Enterprise)

Klucz	Typ	Domyślna	Opis
signature.enabled	bool	false	Włącza usługę składania podpisu.
signature.certificate	string|null	null	Ścieżka pliku certyfikatu.
signature.private_key	string|null	null	Ścieżka pliku klucza prywatnego.
signature.password	string	''	Hasło klucza prywatnego.
signature.extra_certs	list<string>	[]	Ścieżki do dodatkowych certyfikatów łańcucha.
signature.level	string	B-B	Identyfikator poziomu podpisu.

Services::pdfSigner() zwraca null, chyba że signature.enabled ma wartość true, a signature.certificate jest niepusty. Domyślny poziom to B-B. NextPDF Pro dostarcza podstawowy podpis B-B. Poziomy długoterminowej walidacji są odrębną funkcją Enterprise i opisano je w dokumentacji Premium, nie tutaj.

PDF Advanced Electronic Signatures (PAdES) B-T tworzy silnik Core. Sama integracja z CodeIgniter nie dodaje B-T, a Pro dostarcza wyłącznie podstawowy poziom B-B. Ta dokumentacja zostanie zaktualizowana, jeśli B-T pojawi się w Pro.

Urząd znacznika czasu (Time Stamp Authority)

Klucz	Typ	Domyślna	Opis
tsa.url	string|null	null	Adres URL punktu końcowego urzędu znacznika czasu (TSA).
tsa.username	string	''	Nazwa użytkownika do uwierzytelniania podstawowego TSA.
tsa.password	string	''	Hasło do uwierzytelniania podstawowego TSA.
tsa.cert	string|null	null	Ścieżka certyfikatu klienta.
tsa.key	string|null	null	Ścieżka klucza klienta.
tsa.timeout	int	30	Limit czasu żądania w sekundach.
tsa.pinned_public_keys	list<string>	[]	Przypięte klucze publiczne TSA.
tsa.warn_on_key_rotation	bool	true	Ostrzega przy rotacji klucza TSA.
tsa.allow_insecure_http	bool	false	Zezwala na nieszyfrowany HTTP do urzędu TSA.

Services::tsaClient() zwraca null, gdy tsa.url ma wartość null lub jest pustym ciągiem znaków. Gdy wybierzesz poziom podpisu wymagający znacznika czasu, mechanizm podpisywania automatycznie dołącza klienta TSA.

Pamięć podręczna OCSP

Klucz	Typ	Domyślna	Opis
ocspCache.enabled	bool	true	Włącza pamięć podręczną odpowiedzi protokołu Online Certificate Status Protocol (OCSP).
ocspCache.ttl	int	86400	Czas życia pamięci podręcznej (TTL) w sekundach.
ocspCache.directory	string|null	null	Katalog pamięci podręcznej; domyślnie ustawiany przez silnik, gdy wartością jest null.

Renderer HTML w Chrome (NextPDF Artisan)

Klucz	Typ	Domyślna	Opis
artisan.chrome_binary	string|null	null	Ścieżka pliku binarnego Chrome/Chromium.
artisan.render_timeout	int	30	Limit czasu renderowania w sekundach.
artisan.default_css	string	''	Domyślny arkusz stylów.
artisan.no_sandbox	bool	false	Przekazuje --no-sandbox do Chrome.
artisan.max_html_size	int	5000000	Maksymalny rozmiar wejściowego kodu HTML w bajtach.

Renderer Chrome jest konfigurowany dla dokumentu tylko wtedy, gdy artisan.chrome_binary jest ustawiony i zainstalowano nextpdf/artisan.

Nadpisywanie za pomocą .env

BaseConfig rozwiązuje nadpisania środowiskowe osobno dla poszczególnych właściwości. Klucz wyszukiwania składa się z krótkiej nazwy klasy zapisanej małymi literami, nextpdf, oraz ścieżki właściwości. Do adresowania zagnieżdżonych kluczy tablic używaj kropek. Akceptowane są zarówno formy z kropkami, jak i z podkreśleniami.

.env

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

Przedrostek to krótka nazwa klasy zapisana małymi literami. Pozostaje nextpdf, mimo że sama klasa jest zapisana jako NextPdf. Można też użyć w pełni kwalifikowanej formy (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Nadpisywanie przez rozszerzenie klasy

Aby mieć typowaną konfigurację kontrolowaną wersjonowaniem, rozszerz klasę pakietu w katalogu app/Config/. CodeIgniter wczytuje klasę aplikacji zamiast domyślnej klasy pakietu. Ten plik deklaruje klasę i nie powoduje żadnych efektów ubocznych. Dzięki temu spełnia wymaganie PSR-1: plik albo deklaruje symbole, albo wykonuje logikę z efektami ubocznymi, ale nie jedno i drugie (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,
    ];
}

Przypadki brzegowe i pułapki

• Nadpisanie pojedynczego zagnieżdżonego klucza za pomocą .env zmienia tylko ten klucz; reszta tablicy zachowuje wartości domyślne.
• Wartości .env są ciągami znaków. CodeIgniter rzutuje true/false oraz ciągi liczbowe. Wartości, które mają pozostać dosłownymi ciągami znaków, ujmij w cudzysłów.
• Rozszerzenie klasy za pomocą częściowej tablicy defaults zastępuje całą tablicę. Uwzględnij każdy klucz, jak pokazano powyżej.

Uwagi dotyczące bezpieczeństwa

Ścieżki do certyfikatów i kluczy trzymaj poza systemem kontroli wersji. Dostarczaj je przez .env lub menedżera sekretów. tsa.allow_insecure_http musi pozostać false w środowisku produkcyjnym. Zobacz /integrations/codeigniter/security-and-operations/.

Zgodność

• Plik rozszerzający konfigurację aplikacji deklaruje jedną klasę i nie powoduje efektów ubocznych (PSR-1 §x1.x1.p3).

Kontekst komercyjny

Rdzeń NextPDF jest objęty licencją Apache-2.0. Klucze signature.* i pdfa działają tylko wtedy, gdy zainstalowano NextPDF Pro lub Enterprise. Pakiet CodeIgniter udostępnia odpowiadające tym kluczom metody usług. Metody te zwracają null, dopóki nie zainstalujesz odpowiedniego pakietu Premium. Zobacz </get-license/?intent=codeigniter-signing>.

Zobacz też

• /integrations/codeigniter/install/ — instalacja pakietu.
• /integrations/codeigniter/quickstart/ — pierwszy plik PDF.
• /integrations/codeigniter/production-usage/ — kontrolery i zadania kolejkowe z wstrzykiwaniem zależności (DI).
• /integrations/codeigniter/security-and-operations/ — utwardzanie konfiguracji podpisywania oraz ścieżek.