Configurazione del bundle Symfony NextPDF

In breve

L’intero comportamento del bundle si configura sotto la chiave radice nextpdf in config/packages/nextpdf.yaml. Tutte le chiavi hanno un valore predefinito, quindi la configurazione è facoltativa. Questa pagina riflette esattamente Configuration.php.

Albero di configurazione

Lo schema è definito da NextPDF\Symfony\DependencyInjection\Configuration. I valori non validi vengono rifiutati durante la compilazione del container con un’eccezione Symfony InvalidConfigurationException.

Chiavi di primo livello

Chiave	Tipo	Predefinito	Convalida
page_format	enum	A4	uno tra A4, A3, A5, Letter, Legal, Tabloid
orientation	enum	P	uno tra P, L
unit	enum	mm	uno tra pt, mm, cm, in
pdfa	scalare	null	uno tra null, 4, 4e, 4f
fonts_path	scalare	%kernel.project_dir%/resources/fonts	—
cache_path	scalare	%kernel.cache_dir%/nextpdf	—
image_cache_mb	intero	50	minimo 0
font_cache_locking	booleano	true	—
preload_fonts	elenco di stringhe	[]	—

icc_profile

Chiave	Tipo	Predefinito
icc_profile.rgb	scalare	null
icc_profile.cmyk	scalare	null

defaults

Si applica a ogni documento prodotto da PdfFactory.

Chiave	Tipo	Predefinito
defaults.creator	scalare	NextPDF
defaults.author	scalare	(vuoto)
defaults.language	scalare	en
defaults.margin_top	float	10.0
defaults.margin_right	float	10.0
defaults.margin_bottom	float	10.0
defaults.margin_left	float	10.0
defaults.font_family	scalare	dejavusans
defaults.font_size	float	12.0
defaults.trim_box	variabile	null
defaults.bleed_box	variabile	null

PdfFactory legge creator, author e language da questa sezione e li applica a ogni nuovo documento. Le chiavi rimanenti vengono memorizzate come parametri del container per l’uso da parte del motore.

artisan

Ha effetto soltanto quando nextpdf/artisan è installato e rilevato.

Chiave	Tipo	Predefinito
artisan.chrome_binary	scalare	null
artisan.render_timeout	intero	30
artisan.default_css	scalare	(vuoto)
artisan.no_sandbox	booleano	false
artisan.max_html_size	intero	5000000

signature

Ha effetto soltanto quando nextpdf/premium è installato. Quando sono presenti il bundle e il livello Pro, la configurazione di firma supportata è il profilo baseline B-B. Il nodo level accetta i valori stringa elencati di seguito per compatibilità di schema con la famiglia più ampia di configurazioni NextPDF. La capacità di firma fornita da questo bundle è B-B. I profili oltre B-B sono documentati separatamente nella documentazione NextPDF Premium e non sono dichiarati qui.

Chiave	Tipo	Predefinito	Convalida
signature.enabled	booleano	false	—
signature.certificate	scalare	null	—
signature.private_key	scalare	null	—
signature.password	scalare	(vuoto)	—
signature.extra_certs	elenco di stringhe	[]	—
signature.level	enum	B-B	set accettato: B-B, B-T, B-LT, B-LTA (B-B fornito; B-T/B-LT/B-LTA sono valori di compatibilità di schema, non capacità Pro fornita)

Il compiler pass registra un servizio signer solo quando signature.enabled è true e signature.certificate è impostato; in caso contrario, la sezione rimane inerte.

tsa

Configurazione del client Time Stamp Authority, utilizzata dalla firma Pro quando è configurata.

Chiave	Tipo	Predefinito
tsa.url	scalare	null
tsa.username	scalare	(vuoto)
tsa.password	scalare	(vuoto)
tsa.cert	scalare	null
tsa.key	scalare	null
tsa.timeout	intero	30
tsa.allow_insecure_http	booleano	false
tsa.pinned_public_keys	elenco di stringhe	[]
tsa.warn_on_key_rotation	booleano	true

Un servizio client TSA viene registrato soltanto quando tsa.url è impostato.

ocsp_cache

Chiave	Tipo	Predefinito
ocsp_cache.enabled	booleano	true
ocsp_cache.ttl	intero	86400
ocsp_cache.directory	scalare	null

messenger

Parametri per la generazione asincrona, utilizzati quando symfony/messenger è installato.

Chiave	Tipo	Predefinito
messenger.transport	scalare	async
messenger.timeout	intero	120
messenger.retries	intero	3

Configurazione di riferimento

Un file di configurazione che mostra tutte le sezioni con i relativi valori predefiniti:

nextpdf:
    page_format: A4
    orientation: P
    unit: mm
    pdfa: ~
    fonts_path: '%kernel.project_dir%/resources/fonts'
    cache_path: '%kernel.cache_dir%/nextpdf'
    image_cache_mb: 50
    font_cache_locking: true
    preload_fonts: []
    icc_profile:
        rgb: ~
        cmyk: ~
    defaults:
        creator: NextPDF
        author: ''
        language: en
        margin_top: 10.0
        margin_right: 10.0
        margin_bottom: 10.0
        margin_left: 10.0
        font_family: dejavusans
        font_size: 12.0
        trim_box: ~
        bleed_box: ~
    artisan:
        chrome_binary: ~
        render_timeout: 30
        default_css: ''
        no_sandbox: false
        max_html_size: 5000000
    signature:
        enabled: false
        certificate: ~
        private_key: ~
        password: ''
        extra_certs: []
        level: B-B
    tsa:
        url: ~
        username: ''
        password: ''
        cert: ~
        key: ~
        timeout: 30
        allow_insecure_http: false
        pinned_public_keys: []
        warn_on_key_rotation: true
    ocsp_cache:
        enabled: true
        ttl: 86400
        directory: ~
    messenger:
        transport: async
        timeout: 120
        retries: 3

Servizi del container e alias

Il bundle carica le definizioni dei servizi da config/services.php. La tabella seguente riflette esattamente quel file.

ID servizio	Condiviso	Pubblico	Note
NextPDF\Typography\FontRegistry	sì	—	costruito da nextpdf.fonts_path; logger PSR-3 facoltativo
NextPDF\Contracts\FontRegistryInterface	(alias)	sì	alias di FontRegistry
NextPDF\Graphics\ImageRegistry	sì	—	LRU limitata; con tag kernel.reset (reset)
NextPDF\Core\DocumentFactory	sì	—	condivide i due registry
NextPDF\Contracts\DocumentFactoryInterface	(alias)	sì	alias di DocumentFactory
NextPDF\Symfony\Service\PdfFactory	sì	sì	legge defaults, pdfa, artisan come parametri
NextPDF\Contracts\PdfDocumentInterface	no	sì	factory [PdfFactory, create]
NextPDF\Core\Document	(alias)	—	alias di PdfDocumentInterface
nextpdf.document	(alias)	sì	alias di PdfDocumentInterface
NextPDF\Symfony\Http\PdfResponse	—	sì	helper stateless

Il bundle registra inoltre i binding per i contratti EInvoice (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) solo quando esistono le corrispondenti classi di implementazione Premium. Ciascuno viene registrato come non condiviso, così i chiamanti ricevono una nuova istanza. Lo stato del parser relativo alla singola chiamata non si propaga mai tra le richieste.

Condivisi e non condivisi

nextpdf.document (e i suoi alias) è non condiviso: ogni risoluzione del container restituisce un documento distinto. In base a PSR-11, un container può restituire un valore diverso a chiamate get() successive con lo stesso identificatore — PSR-11 §1.1.2. Il font registry è condiviso e, dopo il warmup, bloccato. I dati strutturali dei font vengono quindi analizzati una sola volta per processo e non possono essere modificati durante la richiesta.

I servizi FontRegistry e ImageRegistry accettano un Psr\Log\LoggerInterface facoltativo, associato tramite nullOnInvalid(). Il logger è un collaboratore facoltativo e sostituibile, coerente con il contratto del logger PSR-3 (PSR-3).

Autowiring

PdfFactory, PdfResponse, l’interfaccia della factory dei documenti e l’interfaccia del font registry sono pubblici. Possono essere recuperati dal container o usati come type-hint in controller e servizi con autowiring. L’iniezione tramite costruttore di NextPDF\Symfony\Service\PdfFactory è il punto di ingresso consigliato.

Casi limite e accorgimenti

• pdfa impostato senza Pro — il valore viene memorizzato ma ignorato. PdfFactory applica PDF/A solo quando l’estensione Pro viene rilevata al momento della compilazione.
• image_cache_mb: 0 — valido; disabilita la cache LRU delle immagini. I valori negativi vengono rifiutati al momento della compilazione.
• signature.enabled: true senza signature.certificate — il servizio signer non viene registrato; la configurazione rimane silenziosamente inerte per scelta progettuale.
• %kernel.*% segnaposto — i valori predefiniti di fonts_path e cache_path usano parametri del container Symfony; sovrascriverli con percorsi assoluti solo quando serve un percorso letterale.

Conformità

Ogni riga contiene un’asserzione normativa formulata in questa pagina, ancorata a un reference_id completo a 64 cifre esadecimali dal corpus SDO gated. La provenienza (manifesto del corpus, trasporto di recupero) si trova in _sidecars/rag-citations.yaml.

Specifica	Clausola	reference_id	Asserzione
PSR-11	psr_11_container#1.1.2.p3.b		get() può restituire valori diversi a ogni risoluzione
PSR-3	psr_3_logger#x3.p17		collaboratore LoggerInterface facoltativo

Contesto commerciale

Le sezioni signature e tsa hanno effetto soltanto quando è installato nextpdf/premium (Pro). È una capacità Pro facoltativa; il bundle Core documentato qui non richiede alcuna modifica al codice per adottarla. Vedere </get-license/?intent=symfony-pro>.

Vedere anche

• /integrations/symfony/install/ — installare e registrare il bundle.
• /integrations/symfony/overview/ — riepilogo delle funzionalità.
• /integrations/symfony/production-usage/ — sicurezza dei worker e pattern asincroni.
• /integrations/symfony/boot-and-discovery/ — come la configurazione viene risolta durante il boot.