Konfiguracja pakietu NextPDF dla Laravel

W skrócie

config/nextpdf.php publikuje się za pomocą polecenia php artisan vendor:publish --tag=nextpdf-config. Każdy klucz ma odpowiadającą mu zmienną środowiskową oraz zakodowaną na stałe wartość domyślną. Na tej stronie wymieniono wszystkie klucze w postaci, w jakiej występują w pakietowym pliku config/nextpdf.php.

Instalacja

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

Podczas register() dostawca scala również domyślne ustawienia pakietu pod kluczem konfiguracji nextpdf. Nieustawione klucze przyjmują wtedy wartości podane poniżej, jeszcze przed opublikowaniem pliku konfiguracyjnego.

Przegląd koncepcyjny

Większość zmiennych środowiskowych używa nazwy w formacie NEXTPDF_* albo starszej nazwy TCPDF_*. Starszy prefiks jest dostępny w okresie przejściowym opisanym w pliku UPGRADE.md. W nowych wdrożeniach używaj NEXTPDF_*. Plik konfiguracyjny ustala wartości w tej kolejności: zmienna środowiskowa → wartość z opublikowanego pliku → wartość domyślna pakietu.

Powierzchnia API — klucze konfiguracji

Układ dokumentu

Klucz	Zmienna środowiskowa (podstawowa)	Domyślna wartość	Efekt
page_format	NEXTPDF_PAGE_FORMAT	A4	Domyślny format strony: A4, A3, A5, Letter, Legal lub Tabloid
orientation	NEXTPDF_ORIENTATION	P	Pionowa (P) lub pozioma (L)
unit	NEXTPDF_UNIT	mm	Jednostka miary: pt, mm, cm lub in
defaults.creator	NEXTPDF_CREATOR	NextPDF	Metadane twórcy dokumentu; stosowane przy wiązaniu PdfDocumentInterface
defaults.author	NEXTPDF_AUTHOR	(puste)	Metadane autora; stosowane tylko wtedy, gdy wartość jest niepusta
defaults.language	NEXTPDF_LANG	en	Język dokumentu; stosowany przy wiązaniu dokumentu
defaults.margin_top / _right / _bottom / _left	—	10	Domyślne marginesy
defaults.font_family	—	dejavusans	Domyślna rodzina czcionek
defaults.font_size	—	12	Domyślny rozmiar czcionki
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] w punktach albo null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] w punktach albo null

Dostawca stosuje defaults.creator, defaults.language oraz (gdy ustawiono) defaults.author w każdym nowo rozwiązywanym dokumencie. Pomija defaults.author, gdy wartość jest pusta.

Archiwizacja i kolor

Klucz	Zmienna środowiskowa (podstawowa)	Domyślna wartość	Efekt
pdfa	NEXTPDF_PDFA	null	Poziom archiwizacji PDF/A: null, 4, 4e lub 4f. Wartość inna niż null włącza PDF/A dla wiązania dokumentu i wymaga nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Katalog dodatkowych czcionek TrueType; ustawia ścieżkę wyszukiwania rejestru czcionek
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Katalog pamięci podręcznej przetworzonych czcionek i plików tymczasowych
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Ścieżka profilu ICC RGB; wymagana dla PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Opcjonalny profil ICC CMYK do procesów druku
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Używa flock dla pamięci podręcznej czcionek, aby zapobiec jej uszkodzeniu przy jednoczesnym zapisie przez procesy robocze kolejki

Wartość pdfa inna niż null wymaga edycji Premium. Bez nextpdf/premium próba rozwiązania wiązania dokumentu z ustawionym pdfa zgłasza błąd „klasa nie znaleziona” dla typu wersji PDF/A. Ta strona nie opisuje zachowania archiwizacji w edycji Premium. Zobacz dokumentację edycji Premium.

Pamięć procesów roboczych (długo działające środowiska wykonawcze)

Klucz	Zmienna środowiskowa (podstawowa)	Domyślna wartość	Efekt
preload_fonts	—	[]	Bezwzględne ścieżki plików czcionek przetwarzane przy starcie procesu roboczego. Rejestr czcionek zostaje zablokowany po wstępnym przygotowaniu
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Budżet pamięci podręcznej obrazów działającej według algorytmu „najdawniej używane” (LRU), w megabajtach (MB). 0 wyłącza buforowanie. Dostawca nie wymusza żadnego ograniczenia górnego

Dostawca nie wymusza górnego ograniczenia budżetu pamięci podręcznej obrazów. Aby go ograniczyć, użyj limitu pamięci kontenera lub php.inimemory_limit. Plik konfiguracyjny zaleca praktyczne maksimum 256 MB.

Podpis cyfrowy (Premium)

Klucz	Zmienna środowiskowa (podstawowa)	Domyślna wartość	Efekt
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Gdy false lub gdy certyfikat jest pusty, SignerInterface rozwiązuje się do null
signature.certificate	NEXTPDF_SIGN_CERT	null	Ścieżka certyfikatu podpisującego
signature.private_key	NEXTPDF_SIGN_KEY	null	Ścieżka klucza prywatnego
signature.password	NEXTPDF_SIGN_PASSWORD	(puste)	Hasło klucza
signature.extra_certs	—	[]	Ścieżki certyfikatów pośrednich urzędów certyfikacji
signature.level	NEXTPDF_SIGN_LEVEL	B-B	Poziom bazowy zaawansowanych podpisów elektronicznych PDF (PAdES) przekazywany do podpisującego

Pakiet Core opisany na tej stronie nie dostarcza implementacji podpisującego; SignerInterface rozwiązuje się do null, dopóki nie dostarczy jej nextpdf/premium. W edycji Premium level: B-B tworzy podpis bazowy PAdES B-B. Wyższe poziomy bazowe PAdES zależą od skonfigurowanego urzędu znacznika czasu oraz możliwości dostępnych w edycji Premium; ta strona nie opisuje tych poziomów.

Urząd znacznika czasu

Klucz	Zmienna środowiskowa (podstawowa)	Domyślna wartość	Efekt
tsa.url	NEXTPDF_TSA_URL	null	Punkt końcowy urzędu znacznika czasu (TSA). Gdy jest pusty, TsaClient rozwiązuje się do null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(puste)	Poświadczenia HTTP do TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Certyfikat / klucz klienta na potrzeby wzajemnego uwierzytelniania TLS (mTLS) z TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	Limit czasu HTTP w sekundach dla klienta PSR-18
tsa.pinned_public_keys	—	[]	Przypięcia Base64 SHA-256 dla SubjectPublicKeyInfo (SPKI) (RFC 7469). Pusta wartość wyłącza przypinanie
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Emituje ostrzeżenie, gdy TSA przedstawia nieprzypięte SPKI
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Zezwala na nieszyfrowany ruch HTTP do TSA. W środowisku produkcyjnym pozostaw false

Pamięć podręczna odpowiedzi OCSP

Klucz	Zmienna środowiskowa (podstawowa)	Domyślna wartość	Efekt
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Buforuje odpowiedzi protokołu sprawdzania stanu certyfikatu online (OCSP) podczas walidacji
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	Czas życia pamięci podręcznej (TTL) w sekundach
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Katalog pamięci podręcznej; null oznacza przechowywanie pamięci podręcznej wyłącznie w pamięci

Kolejka

Klucz	Zmienna środowiskowa (podstawowa)	Domyślna wartość	Efekt
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Połączenie kolejki; null oznacza użycie połączenia domyślnego
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Kolejka, do której trafia GeneratePdfJob
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Limit czasu pojedynczego zadania w sekundach

Renderer Chrome CDP (rozszerzenie Artisan)

Klucz	Zmienna środowiskowa (podstawowa)	Domyślna wartość	Efekt
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	wartość ze środowiska lub brak ustawienia	Ścieżka do pliku binarnego Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Limit czasu renderowania w sekundach
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(puste)	Domyślny CSS wstrzykiwany do renderowanego kodu HTML
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Wyłącza piaskownicę Chrome
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Maksymalny rozmiar wejściowego kodu HTML w bajtach

Sekcja artisan ma wpływ na wiązanie dokumentu tylko wtedy, gdy dostępna jest klasa fabryki przeglądarki Chrome (rozszerzenie nextpdf/artisan). Jeśli tej klasy nie ma, sekcja jest ignorowana.

Przykład kodu — środowisko produkcyjne

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),
    ],
];

Przypadki brzegowe i pułapki

• signature.enabled = true z pustym signature.certificate nadal rozwiązuje SignerInterface do null; obie wartości muszą być ustawione.
• tsa.url = null wymusza rozwiązywanie TsaClient jako null, nawet gdy inne klucze tsa.* są wypełnione.
• signature.level = null powoduje powrót podpisującego do PAdES B-B.
• Gdy image_cache_mb ma wartość null (a nie 0), wraca do domyślnej wartości 50 MB; 0 jawnie wyłącza buforowanie.
• Starsze zmienne środowiskowe TCPDF_* nadal są odczytywane, ale są przestarzałe. Przejdź na NEXTPDF_*.

Wydajność

Odczyt konfiguracji korzysta z dostępu do tablicy o złożoności O(1). preload_fonts kosztem jednorazowego przetwarzania o złożoności O(f) przy starcie procesu roboczego obniża opóźnienie pierwszego żądania. Większa wartość image_cache_mb ogranicza wielokrotne dekodowanie obrazów kosztem pamięci zajmowanej przez proces.

Uwagi dotyczące bezpieczeństwa

tsa.allow_insecure_http osłabia zaufanie do znaczników czasu i w środowisku produkcyjnym musi pozostać false. Adresy URL TSA powinny pochodzić wyłącznie z zaufanej konfiguracji. Jeśli udostępniasz je przez panel administracyjny, użyj zapory wyjściowej lub polityki DNS, aby ograniczyć fałszowanie żądań. Zobacz /integrations/laravel/security-and-operations/.

Zgodność

Żadna norma nie reguluje kształtu pliku konfiguracyjnego. Wszystkie klucze są weryfikowane względem pakietowego pliku config/nextpdf.php w udokumentowanej rewizji. Semantykę poziomu podpisu określa edycja Premium; wykracza ona poza zakres tej strony Core.

Kontekst komercyjny

Sekcje signature i tsa obsługują podpisywanie w edycji Premium, gdy zainstalowano nextpdf/premium. Ta opcjonalna funkcja Enterprise nie wymaga żadnych zmian w kodzie pakietu Core. Zobacz https://nextpdf.dev/get-license/?intent=laravel-signing.

Zobacz też

• /integrations/laravel/install/ — publikacja pliku konfiguracyjnego
• /integrations/laravel/production-usage/ — zobacz konfigurację używaną w rzeczywistym kontrolerze
• /integrations/laravel/security-and-operations/ — zabezpiecz ustawienia TSA i kolejki
• /integrations/laravel/boot-and-discovery/ — sprawdź, którym wiązaniem steruje każdy klucz