Configuração do pacote Laravel do NextPDF

Visão geral

config/nextpdf.php é publicado por php artisan vendor:publish --tag=nextpdf-config. Cada chave tem um fallback por variável de ambiente e um valor padrão fixo no código. Esta página lista cada chave conforme aparece no config/nextpdf.php do pacote.

Instalar

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

Durante register(), o provider também mescla os valores padrão do pacote sob a chave de configuração nextpdf. As chaves não definidas passam então a recorrer aos valores abaixo, mesmo antes de você publicar o arquivo de config.

Visão conceitual

A maioria das variáveis de ambiente aceita tanto um nome NEXTPDF_* quanto um nome legado TCPDF_*. O prefixo legado fica disponível durante o período de transição documentado em UPGRADE.md. Use NEXTPDF_* em novas implantações. O arquivo de config resolve os valores nesta ordem: variável de ambiente → valor do arquivo publicado → valor padrão do pacote.

Superfície da API — chaves de configuração

Layout do documento

Chave	Env (primária)	Padrão	Efeito
page_format	NEXTPDF_PAGE_FORMAT	A4	Formato de página padrão: A4, A3, A5, Letter, Legal ou Tabloid
orientation	NEXTPDF_ORIENTATION	P	Retrato (P) ou paisagem (L)
unit	NEXTPDF_UNIT	mm	Unidade de medida: pt, mm, cm ou in
defaults.creator	NEXTPDF_CREATOR	NextPDF	Metadados do criador do documento; aplicados ao binding PdfDocumentInterface do contêiner
defaults.author	NEXTPDF_AUTHOR	(vazio)	Metadados do autor; aplicados apenas quando não vazio
defaults.language	NEXTPDF_LANG	en	Idioma do documento; aplicado ao binding do documento
defaults.margin_top / _right / _bottom / _left	—	10	Margens padrão
defaults.font_family	—	dejavusans	Família de fontes padrão
defaults.font_size	—	12	Tamanho de fonte padrão
defaults.trim_box	—	null	TrimBox [left, bottom, right, top] em pontos, ou null
defaults.bleed_box	—	null	BleedBox [left, bottom, right, top] em pontos, ou null

O provider aplica defaults.creator, defaults.language e (quando definido) defaults.author a cada documento recém-resolvido. O provider ignora defaults.author quando o valor está vazio.

Arquivamento e cor

Chave	Env (primária)	Padrão	Efeito
pdfa	NEXTPDF_PDFA	null	Nível de arquivamento PDF/A: null, 4, 4e ou 4f. Um valor não nulo habilita PDF/A no binding do documento e exige nextpdf/premium
fonts_path	NEXTPDF_FONTS_PATH	resource_path('fonts')	Diretório de fontes TrueType adicionais; define o caminho de busca do registro de fontes
cache_path	NEXTPDF_CACHE_PATH	storage_path('framework/cache/tcpdf')	Diretório de cache para fontes processadas e arquivos temporários
icc_profile.rgb	NEXTPDF_ICC_PROFILE_RGB	null	Caminho do perfil ICC RGB; obrigatório para PDF/A
icc_profile.cmyk	NEXTPDF_ICC_PROFILE_CMYK	null	Perfil ICC CMYK opcional para fluxos de impressão
font_cache_locking	NEXTPDF_FONT_CACHE_LOCKING	true	Usa flock no cache de fontes para evitar corrupção quando workers de fila concorrentes escrevem

Um valor pdfa não nulo exige o nível Premium. Sem nextpdf/premium, resolver o binding do documento com pdfa definido gera um erro de classe não encontrada para o tipo de versão PDF/A. Esta página não documenta o comportamento de arquivamento Premium. Consulte a documentação Premium.

Memória do worker (runtimes de longa duração)

Chave	Env (primária)	Padrão	Efeito
preload_fonts	—	[]	Caminhos absolutos de arquivos de fonte processados na inicialização do worker. O registro de fontes é bloqueado após o aquecimento
image_cache_mb	NEXTPDF_IMAGE_CACHE_MB	50	Orçamento do cache de imagens menos recentemente usadas (LRU), em megabytes (MB). 0 desabilita o cache. Nenhum limite superior é imposto no nível do provider

O orçamento do cache de imagens não tem limite superior imposto pelo provider. Use um limite de memória do contêiner ou php.inimemory_limit para restringi-lo. O arquivo de config recomenda um máximo prático de 256 MB.

Assinatura digital (Premium)

Chave	Env (primária)	Padrão	Efeito
signature.enabled	NEXTPDF_SIGN_ENABLED	false	Quando false, ou quando o certificado estiver vazio, SignerInterface resolve para null
signature.certificate	NEXTPDF_SIGN_CERT	null	Caminho do certificado de assinatura
signature.private_key	NEXTPDF_SIGN_KEY	null	Caminho da chave privada
signature.password	NEXTPDF_SIGN_PASSWORD	(vazio)	Senha da chave
signature.extra_certs	—	[]	Caminhos dos certificados de CA intermediária
signature.level	NEXTPDF_SIGN_LEVEL	B-B	Nível de baseline de PDF Advanced Electronic Signatures (PAdES) passado ao signer

O pacote Core documentado aqui não inclui uma implementação de signer; SignerInterface resolve para null até que nextpdf/premium forneça uma. Com o Premium, level: B-B produz uma assinatura baseline PAdES B-B. Baselines PAdES superiores dependem de uma autoridade de carimbo de tempo configurada e do recurso Premium; esta página não documenta esses níveis.

Autoridade de carimbo de tempo

Chave	Env (primária)	Padrão	Efeito
tsa.url	NEXTPDF_TSA_URL	null	Endpoint da autoridade de carimbo de tempo (TSA). Quando vazio, TsaClient resolve para null
tsa.username / tsa.password	NEXTPDF_TSA_USERNAME / _PASSWORD	(vazio)	Credenciais HTTP da TSA
tsa.cert / tsa.key	NEXTPDF_TSA_CERT / _KEY	null	Certificado / chave de cliente para Transport Layer Security mútuo (mTLS) com a TSA
tsa.timeout	NEXTPDF_TSA_TIMEOUT	30	Timeout HTTP em segundos para o cliente PSR-18
tsa.pinned_public_keys	—	[]	Pins de SubjectPublicKeyInfo (SPKI) SHA-256 em Base64 (RFC 7469). Vazio desabilita o pinning
tsa.warn_on_key_rotation	NEXTPDF_TSA_WARN_ROTATION	true	Emite um aviso quando a TSA apresenta um SPKI não fixado
tsa.allow_insecure_http	NEXTPDF_TSA_ALLOW_INSECURE_HTTP	false	Permite HTTP em texto puro para a TSA. Mantenha como false em produção

Cache de respostas OCSP

Chave	Env (primária)	Padrão	Efeito
ocsp_cache.enabled	NEXTPDF_OCSP_CACHE_ENABLED	true	Armazena em cache as respostas do Online Certificate Status Protocol (OCSP) durante a validação
ocsp_cache.ttl	NEXTPDF_OCSP_CACHE_TTL	86400	TTL do cache em segundos
ocsp_cache.directory	NEXTPDF_OCSP_CACHE_DIR	null	Diretório de cache; null mantém o cache apenas em memória

Fila

Chave	Env (primária)	Padrão	Efeito
queue.connection	NEXTPDF_QUEUE_CONNECTION	null	Conexão da fila; null usa a conexão padrão
queue.queue	NEXTPDF_QUEUE_NAME	pdf	Fila para a qual GeneratePdfJob é enviado
queue.timeout	NEXTPDF_QUEUE_TIMEOUT	120	Timeout por job em segundos

Renderizador Chrome CDP (extensão Artisan)

Chave	Env (primária)	Padrão	Efeito
artisan.chrome_binary	NEXTPDF_ARTISAN_CHROME_BINARY	valor de env ou não definido	Caminho para o binário do Chrome/Chromium
artisan.render_timeout	NEXTPDF_ARTISAN_RENDER_TIMEOUT	30	Timeout de renderização em segundos
artisan.default_css	NEXTPDF_ARTISAN_DEFAULT_CSS	(vazio)	CSS padrão injetado no HTML renderizado
artisan.no_sandbox	NEXTPDF_ARTISAN_NO_SANDBOX	false	Desabilita o sandbox do Chrome
artisan.max_html_size	NEXTPDF_ARTISAN_MAX_HTML_SIZE	5000000	Tamanho máximo de entrada HTML em bytes

A seção artisan só se aplica ao binding do documento quando uma classe de fábrica de navegador Chrome está presente (a extensão nextpdf/artisan). Quando essa classe está ausente, a seção é ignorada.

Exemplo de código — Produção

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

Casos extremos e pegadinhas

• signature.enabled = true com um signature.certificate vazio ainda resolve SignerInterface para null; ambos os valores precisam estar definidos.
• tsa.url = null força TsaClient para null, mesmo que outras chaves tsa.* estejam preenchidas.
• signature.level = null recorre a PAdES B-B no signer.
• image_cache_mb definido como null (não 0) recorre ao valor padrão de 50 MB; 0 desabilita o cache explicitamente.
• As variáveis de ambiente legadas TCPDF_* continuam legíveis, mas estão depreciadas. Migre para NEXTPDF_*.

Desempenho

A leitura da config usa acesso a array O(1). preload_fonts troca um parse único O(f) na inicialização do worker por menor latência na primeira requisição. Um image_cache_mb maior reduz a redecodificação repetida de imagens ao custo de memória residente no processo.

Notas de segurança

tsa.allow_insecure_http enfraquece a confiança no carimbo de tempo e deve permanecer false em produção. As URLs da TSA devem vir apenas de configuração confiável. Se você as expuser por meio de uma superfície administrativa, use firewall de saída ou política de DNS para mitigar falsificação de requisições. Consulte /integrations/laravel/security-and-operations/.

Conformidade

Nenhum padrão normativo rege o formato do arquivo de configuração. Todas as chaves são verificadas contra o config/nextpdf.php do pacote na revisão documentada. O Premium rege a semântica de nível de assinatura, que está fora do escopo desta página Core.

Contexto comercial

As seções signature e tsa acionam a assinatura Premium quando o nextpdf/premium está instalado. Esse recurso Enterprise opcional não exige alterações no código do pacote Core. Consulte https://nextpdf.dev/get-license/?intent=laravel-signing.

Veja também

• /integrations/laravel/install/ — publique o arquivo de config
• /integrations/laravel/production-usage/ — veja a configuração aplicada em um controller real
• /integrations/laravel/security-and-operations/ — proteja a TSA e as configurações de fila
• /integrations/laravel/boot-and-discovery/ — veja qual binding cada chave aciona