Configure o bundle Symfony do NextPDF

Visão geral

Configure todo o comportamento do bundle sob a chave raiz nextpdf em config/packages/nextpdf.yaml. Cada chave tem um padrão; portanto, você só define os valores que quer alterar. Esta página reflete exatamente o Configuration.php.

Árvore de configuração

NextPDF\Symfony\DependencyInjection\Configuration define o esquema. Valores inválidos fazem a construção do contêiner falhar com uma InvalidConfigurationException do Symfony.

Chaves de nível superior

Chave	Tipo	Padrão	Validação
page_format	enum	A4	um entre A4, A3, A5, Letter, Legal, Tabloid
orientation	enum	P	um entre P, L
unit	enum	mm	um entre pt, mm, cm, in
pdfa	scalar	null	um entre null, 4, 4e, 4f
fonts_path	scalar	%kernel.project_dir%/resources/fonts	—
cache_path	scalar	%kernel.cache_dir%/nextpdf	—
image_cache_mb	integer	50	mínimo 0
font_cache_locking	boolean	true	—
preload_fonts	lista de strings	[]	—

icc_profile

Chave	Tipo	Padrão
icc_profile.rgb	scalar	null
icc_profile.cmyk	scalar	null

defaults

Aplica-se a todos os documentos produzidos pelo PdfFactory.

Chave	Tipo	Padrão
defaults.creator	scalar	NextPDF
defaults.author	scalar	(vazio)
defaults.language	scalar	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	scalar	dejavusans
defaults.font_size	float	12.0
defaults.trim_box	variable	null
defaults.bleed_box	variable	null

PdfFactory lê creator, author e language desta seção e os aplica a cada novo documento. O bundle armazena as demais chaves como parâmetros de contêiner para uso do mecanismo.

artisan

Aplica-se apenas quando nextpdf/artisan está instalado e é detectado.

Chave	Tipo	Padrão
artisan.chrome_binary	scalar	null
artisan.render_timeout	integer	30
artisan.default_css	scalar	(vazio)
artisan.no_sandbox	boolean	false
artisan.max_html_size	integer	5000000

signature

Aplica-se apenas quando nextpdf/premium está instalado. Quando o bundle e a camada Pro estão presentes, a configuração de assinatura suportada é o perfil baseline B-B. O nó level aceita os valores de string abaixo para manter compatibilidade de esquema com a família mais ampla de configurações do NextPDF. Este bundle entrega a capacidade de assinatura B-B. Perfis além de B-B são documentados separadamente na documentação do NextPDF Premium e não são reivindicados aqui.

Chave	Tipo	Padrão	Validação
signature.enabled	boolean	false	—
signature.certificate	scalar	null	—
signature.private_key	scalar	null	—
signature.password	scalar	(vazio)	—
signature.extra_certs	lista de strings	[]	—
signature.level	enum	B-B	conjunto aceito: B-B, B-T, B-LT, B-LTA (B-B entregue; B-T/B-LT/B-LTA são valores de compatibilidade de esquema, não capacidade Pro entregue)

O compiler pass registra um serviço de assinatura apenas quando signature.enabled é true e signature.certificate está definido; caso contrário, a seção permanece inerte.

tsa

Configuração do cliente de Time Stamp Authority (TSA), usada pela assinatura Pro quando ela está configurada.

Chave	Tipo	Padrão
tsa.url	scalar	null
tsa.username	scalar	(vazio)
tsa.password	scalar	(vazio)
tsa.cert	scalar	null
tsa.key	scalar	null
tsa.timeout	integer	30
tsa.allow_insecure_http	boolean	false
tsa.pinned_public_keys	lista de strings	[]
tsa.warn_on_key_rotation	boolean	true

O bundle registra um serviço de cliente TSA apenas quando tsa.url está definido.

ocsp_cache

Chave	Tipo	Padrão
ocsp_cache.enabled	boolean	true
ocsp_cache.ttl	integer	86400
ocsp_cache.directory	scalar	null

messenger

Configurações para geração assíncrona, consumidas quando symfony/messenger está instalado.

Chave	Tipo	Padrão
messenger.transport	scalar	async
messenger.timeout	integer	120
messenger.retries	integer	3

Configuração de referência

Um arquivo de configuração que mostra cada seção com seus respectivos padrões:

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

Serviços de contêiner e aliases

O bundle carrega suas definições de serviço a partir de config/services.php. A tabela abaixo reflete esse arquivo exatamente.

ID do serviço	Compartilhado	Público	Notas
NextPDF\Typography\FontRegistry	sim	—	construído a partir de nextpdf.fonts_path; logger opcional conforme PHP Standard Recommendation 3 (PSR-3)
NextPDF\Contracts\FontRegistryInterface	(alias)	sim	alias de FontRegistry
NextPDF\Graphics\ImageRegistry	sim	—	limitado por least-recently-used (LRU); marcado com kernel.reset (reset)
NextPDF\Core\DocumentFactory	sim	—	compartilha os dois registros
NextPDF\Contracts\DocumentFactoryInterface	(alias)	sim	alias de DocumentFactory
NextPDF\Symfony\Service\PdfFactory	sim	sim	lê defaults, pdfa e artisan como parâmetros
NextPDF\Contracts\PdfDocumentInterface	não	sim	factory [PdfFactory, create]
NextPDF\Core\Document	(alias)	—	alias de PdfDocumentInterface
nextpdf.document	(alias)	sim	alias de PdfDocumentInterface
NextPDF\Symfony\Http\PdfResponse	—	sim	auxiliar sem estado

O bundle também registra as ligações de contrato do EInvoice (EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface) apenas quando as classes de implementação Premium correspondentes existem. Cada serviço é marcado como não compartilhado, então cada chamada recebe uma nova instância. O estado do parser por chamada nunca vaza entre requisições.

Compartilhado versus não compartilhado

nextpdf.document (e os aliases dele) é não compartilhado: cada resolução do contêiner retorna um documento distinto. Segundo a PHP Standard Recommendation 11 (PSR-11), um contêiner pode retornar um valor diferente em chamadas get() sucessivas com o mesmo identificador; veja PSR-11 §1.1.2. O registro de fontes é compartilhado e travado após o warmup. Os dados estruturais de fonte são analisados uma vez por processo e não podem ser modificados no meio da requisição.

Os serviços FontRegistry e ImageRegistry aceitam um Psr\Log\LoggerInterface opcional; o Symfony o vincula com nullOnInvalid(). O logger continua sendo um colaborador opcional e substituível, em conformidade com o contrato de logger da PSR-3.

Autowiring

PdfFactory, PdfResponse, a interface da factory de documentos e a interface do registro de fontes são públicas. Elas podem ser obtidas do contêiner ou usadas como type-hint em controllers e serviços com autowiring. A injeção pelo construtor de NextPDF\Symfony\Service\PdfFactory é o ponto de entrada recomendado.

Casos extremos e pegadinhas

• pdfa definido sem o Pro — o valor é armazenado, mas ignorado. O PdfFactory aplica Portable Document Format/Archival (PDF/A) apenas quando a extensão Pro é detectada durante a compilação.
• image_cache_mb: 0 — válido; desativa o cache LRU de imagens. Valores negativos são rejeitados no momento da construção.
• signature.enabled: true sem signature.certificate — o serviço de assinatura não é registrado; a configuração fica inerte, silenciosamente e por design.
• Placeholders %kernel.*% — os padrões de fonts_path e cache_path usam parâmetros de contêiner do Symfony; sobrescreva com caminhos absolutos apenas quando o caminho literal for necessário.

Conformidade

Nesta página, cada linha é uma afirmação normativa vinculada a um reference_id completo de 64 hex do corpus restrito da standards development organization (SDO). A proveniência, incluindo o manifesto do corpus e o transporte de recuperação, está em _sidecars/rag-citations.yaml.

Spec	Cláusula	reference_id	Afirmação
PSR-11	psr_11_container#1.1.2.p3.b		get() pode retornar valores diferentes por resolução
PSR-3	psr_3_logger#x3.p17		Colaborador LoggerInterface opcional

Contexto comercial

As seções signature e tsa se aplicam apenas quando nextpdf/premium (Pro) está instalado. Essa capacidade Pro opcional não exige nenhuma alteração de código no bundle Core documentado aqui. Veja </get-license/?intent=symfony-pro>.

Veja também

• /integrations/symfony/install/ — instale e registre o bundle.
• /integrations/symfony/overview/ — consulte o resumo de capacidades.
• /integrations/symfony/production-usage/ — segurança de workers e padrões assíncronos.
• /integrations/symfony/boot-and-discovery/ — veja como a configuração é resolvida durante o boot.