Het NextPDF-pakket voor Laravel configureren

In één oogopslag

config/nextpdf.php wordt gepubliceerd door php artisan vendor:publish --tag=nextpdf-config. Elke sleutel valt terug op een omgevingsvariabele en een hardgecodeerde standaardwaarde. Deze pagina vermeldt elke sleutel zoals die in de config/nextpdf.php van het pakket voorkomt.

Installeren

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

Tijdens register() voegt de provider ook de standaardwaarden van het pakket toe onder de configuratiesleutel nextpdf. Niet-ingestelde sleutels vallen dan terug op de onderstaande waarden, zelfs voordat je het configuratiebestand publiceert.

Conceptueel overzicht

De meeste omgevingsvariabelen accepteren een NEXTPDF_*-naam of een verouderde TCPDF_*-naam. Het verouderde voorvoegsel blijft beschikbaar tijdens de overgangsperiode die in UPGRADE.md wordt beschreven. Gebruik NEXTPDF_* voor nieuwe implementaties. Het configuratiebestand bepaalt waarden in deze volgorde: omgevingsvariabele → waarde in het gepubliceerde bestand → standaardwaarde van het pakket.

API-oppervlak — configuratiesleutels

Documentindeling

Sleutel	Env (primair)	Standaard	Effect
page_format	NEXTPDF_PAGE_FORMAT	A4	Standaardpaginaformaat: A4, A3, A5, Letter, Legal of Tabloid
orientation	NEXTPDF_ORIENTATION	P	Staand (P) of liggend (L)
unit	NEXTPDF_UNIT	mm	Maateenheid: pt, mm, cm of in
defaults.creator	NEXTPDF_CREATOR	NextPDF	Metadata van de documentmaker; toegepast op de PdfDocumentInterface-binding
defaults.author	NEXTPDF_AUTHOR	(leeg)	Metadata van de auteur; alleen toegepast wanneer niet leeg
defaults.language	NEXTPDF_LANG	en	Documenttaal; toegepast op de documentbinding
defaults.margin_top / _right / _bottom / _left	—	10	Standaardmarges
defaults.font_family	—	dejavusans	Standaardlettertypefamilie
defaults.font_size	—	12	Standaardtekengrootte
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] in punten, of null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] in punten, of null

De provider past defaults.creator, defaults.language en (indien ingesteld) defaults.author toe op elk nieuw opgelost document. De provider slaat defaults.author over wanneer de waarde leeg is.

Archivering en kleur

Sleutel	Env (primair)	Standaard	Effect
pdfa	NEXTPDF_PDFA	null	PDF/A-archiveringsniveau: null, 4, 4e of 4f. Een niet-null-waarde schakelt PDF/A in op de documentbinding en vereist nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Map voor aanvullende TrueType-lettertypen; stelt het zoekpad van het lettertyperegister in
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Cachemap voor geparseerde lettertypen en tijdelijke bestanden
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Pad naar het RGB-ICC-profiel; vereist voor PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Optioneel CMYK-ICC-profiel voor afdrukworkflows
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Gebruikt flock voor de lettertypecache om corruptie te voorkomen wanneer gelijktijdige queue-workers schrijven

Een niet-null-waarde voor pdfa vereist het Premium-niveau. Zonder nextpdf/premium veroorzaakt het oplossen van de documentbinding met pdfa ingesteld een class-not-found-fout voor het PDF/A-versietype. Deze pagina documenteert het Premium-archiveringsgedrag niet. Raadpleeg de Premium-documentatie.

Workergeheugen (langlevende runtimes)

Sleutel	Env (primair)	Standaard	Effect
preload_fonts	—	[]	Absolute paden naar lettertypebestanden die bij het opstarten van de worker worden geparseerd. Na de warming-up wordt het lettertyperegister vergrendeld
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Budget voor de least recently used (LRU) afbeeldingscache in megabytes (MB). 0 schakelt caching uit. Op providerniveau wordt geen bovengrens afgedwongen

Het budget voor de afbeeldingscache heeft geen door de provider afgedwongen bovengrens. Gebruik een geheugenlimiet op containerniveau of php.inimemory_limit om het te beperken. Het configuratiebestand beveelt een praktisch maximum van 256 MB aan.

Digitale handtekening (Premium)

Sleutel	Env (primair)	Standaard	Effect
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Wanneer dit false is, of wanneer het certificaat leeg is, lost SignerInterface op naar null
signature.certificate	NEXTPDF_SIGN_CERT	null	Pad naar het ondertekeningscertificaat
signature.private_key	NEXTPDF_SIGN_KEY	null	Pad naar de privésleutel
signature.password	NEXTPDF_SIGN_PASSWORD	(leeg)	Wachtwoordzin voor de sleutel
signature.extra_certs	—	[]	Paden naar tussenliggende CA-certificaten
signature.level	NEXTPDF_SIGN_LEVEL	B-B	Baseline-niveau voor PDF Advanced Electronic Signatures (PAdES) dat aan de ondertekenaar wordt doorgegeven

Het hier gedocumenteerde Core-pakket bevat geen ondertekenaarimplementatie; SignerInterface lost op naar null totdat nextpdf/premium er een levert. Met Premium produceert level: B-B een PAdES B-B-baselinehandtekening. Hogere PAdES-baselines zijn afhankelijk van een geconfigureerde tijdstempelautoriteit en Premium-functionaliteit; deze pagina documenteert die niveaus niet.

Tijdstempelautoriteit

Sleutel	Env (primair)	Standaard	Effect
tsa.url	NEXTPDF_TSA_URL	null	Endpoint van de tijdstempelautoriteit (TSA). Wanneer dit leeg is, lost TsaClient op naar null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(leeg)	HTTP-inloggegevens voor de TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Clientcertificaat / sleutel voor wederzijdse Transport Layer Security (mTLS) naar de TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	HTTP-time-out in seconden voor de PSR-18-client
tsa.pinned_public_keys	—	[]	Base64-SHA-256-SubjectPublicKeyInfo (SPKI)-pins (RFC 7469). Leeg schakelt pinning uit
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Geeft een waarschuwing wanneer de TSA een niet-gepinde SPKI presenteert
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Staat platte HTTP naar de TSA toe. Laat dit in productie op false staan

OCSP-responscache

Sleutel	Env (primair)	Standaard	Effect
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Cache de responsen van het Online Certificate Status Protocol (OCSP) tijdens validatie
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	Cache-TTL in seconden
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Cachemap; null houdt de cache alleen in het geheugen

Queue

Sleutel	Env (primair)	Standaard	Effect
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Queue-verbinding; null gebruikt de standaardverbinding
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Queue waarnaar GeneratePdfJob wordt gepusht
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Time-out per taak in seconden

Chrome-CDP-renderer (Artisan-extensie)

Sleutel	Env (primair)	Standaard	Effect
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	env-waarde of niet ingesteld	Pad naar het binaire bestand van Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Render-time-out in seconden
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(leeg)	Standaard-CSS die in de gerenderde HTML wordt geïnjecteerd
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Schakelt de Chrome-sandbox uit
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Maximale grootte van de HTML-invoer in bytes

De sectie artisan is alleen van toepassing op de documentbinding wanneer een Chrome-browser-factoryklasse aanwezig is (de nextpdf/artisan-extensie). Als die klasse ontbreekt, wordt de sectie genegeerd.

Codevoorbeeld — Productie

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

Randgevallen en valkuilen

• signature.enabled = true met een leeg signature.certificate lost SignerInterface nog steeds op naar null; beide waarden moeten worden ingesteld.
• tsa.url = null dwingt TsaClient naar null, zelfs als andere tsa.*-sleutels zijn ingevuld.
• signature.level = null valt terug op PAdES B-B bij de ondertekenaar.
• image_cache_mb ingesteld op null (niet 0) valt terug op de standaardwaarde van 50 MB; 0 schakelt caching expliciet uit.
• Verouderde TCPDF_*-omgevingsvariabelen blijven leesbaar maar zijn afgeschaft. Migreer naar NEXTPDF_*.

Prestaties

Het lezen van de configuratie gebruikt arraytoegang met O(1). preload_fonts ruilt een eenmalige O(f)-parse bij het opstarten van de worker in voor lagere latentie bij het eerste verzoek. Een grotere image_cache_mb vermindert herhaald decoderen van afbeeldingen ten koste van het procesresidente geheugen.

Beveiligingsnotities

tsa.allow_insecure_http verzwakt het vertrouwen in tijdstempels en moet in productie false blijven. TSA-URL’s mogen alleen afkomstig zijn uit vertrouwde configuratie. Als je ze via een beheerdersinterface blootstelt, gebruik dan een egress-firewall of DNS-beleid om request forgery te beperken. Zie /integrations/laravel/security-and-operations/.

Conformiteit

Geen normatieve standaard bepaalt de vorm van het configuratiebestand. Alle sleutels zijn geverifieerd ten opzichte van de config/nextpdf.php van het pakket bij de gedocumenteerde revisie. Premium bepaalt de semantiek van het handtekeningniveau, die buiten de reikwijdte van deze Core-pagina valt.

Commerciële context

De secties signature en tsa sturen het ondertekenen met Premium aan wanneer nextpdf/premium is geïnstalleerd. Deze optionele Enterprise-functionaliteit vereist geen codewijzigingen in het Core-pakket. Zie https://nextpdf.dev/get-license/?intent=laravel-signing.

Zie ook

• /integrations/laravel/install/ — publiceer het configuratiebestand
• /integrations/laravel/production-usage/ — zie de configuratie toegepast in een echte controller
• /integrations/laravel/security-and-operations/ — verstevig de TSA- en queue-instellingen
• /integrations/laravel/boot-and-discovery/ — zie welke binding elke sleutel aanstuurt