Solução de problemas do bundle NextPDF para Symfony

Visão geral

Em geral, os problemas vêm de uma destas quatro áreas: descoberta, validação da configuração, ligação no container ou roteamento do Messenger. Cada seção relaciona um sintoma ao comportamento do bundle por trás dele e, depois, fornece um comando do console para confirmar a correção.

O bundle não está registrado

Sintoma: você não consegue fazer o autowire de PdfFactory, ou debug:container nextpdf não retorna nada.

Causa: o bundle não foi adicionado ao config/bundles.php. Talvez o Flex não tenha sido executado, ou a aplicação talvez não use o Flex.

Resolução:

php bin/console debug:container nextpdf

Se o comando não retornar nenhum serviço, adicione o bundle manualmente:

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

O composer.json do bundle traz a dica de registro automático em extra.symfony.bundles. Ela se aplica apenas a aplicações com o Flex habilitado.

A inicialização falha por uma extensão PHP ausente

Sintoma: o kernel lança uma RuntimeException que menciona ext-mbstring ou ext-zlib durante a inicialização.

Causa: isso vem de NextPdfExtension::guardRequiredExtensions(), a proteção fail-fast intencional do bundle. Não se trata de um defeito.

Resolução: habilite a extensão indicada no php.ini e reinicie o runtime. Confirme com:

php -m | grep -E 'mbstring|zlib'

A configuração é rejeitada em tempo de build

Sintoma: o Symfony lança uma Symfony\Component\Config\Definition\Exception\InvalidConfigurationException durante cache:clear ou cache:warmup.

Causa: um valor está fora do schema. O Configuration.php define estas restrições:

• page_format deve ser um de A4, A3, A5, Letter, Legal, Tabloid.
• orientation deve ser P ou L.
• unit deve ser um de pt, mm, cm, in.
• pdfa deve ser null, 4, 4e ou 4f.
• image_cache_mb deve ser >= 0.

Resolução: imprima a configuração mesclada e, depois, corrija a chave que falhou:

php bin/console debug:config nextpdf

PDF/A ou assinatura não têm efeito

Sintoma: pdfa ou a seção signature está definida, mas a saída é um arquivo Portable Document Format (PDF) comum.

Causa: esses recursos exigem o nextpdf/premium. Em tempo de compilação, o PdfFactory aplica PDF/A apenas quando detecta a extensão Pro. O compiler pass registra um signer apenas quando signature.enabled é true e signature.certificate está definido.

Resolução: confirme que o Premium está instalado e que o serviço de signer existe:

composer show nextpdf/premium
php bin/console debug:container --show-private | grep -i signer

Se o Premium estiver ausente, o bundle armazena a configuração, mas a deixa inerte de propósito. No bundle com o Pro, a capacidade de assinatura documentada é o perfil de referência B-B. A documentação do NextPDF Premium cobre perfis além do B-B.

A renderização com o Chrome não faz nada

Sintoma: a configuração de artisan é ignorada.

Causa: a renderização via Chrome DevTools Protocol (CDP) exige o nextpdf/artisan. O compiler pass verifica sua presença com class_exists em tempo de compilação. Se a extensão estiver ausente, o renderizador não é conectado.

Resolução:

composer show nextpdf/artisan
php bin/console cache:clear   # re-run the compile-time probe

A verificação é executada durante a compilação do container. Depois de instalar a extensão, execute um novo cache:clear.

O handler do Messenger nunca é chamado

Sintoma: você despacha GeneratePdfMessage, mas nenhum PDF é gravado.

Causas e resoluções:

• Mensagem não roteada — adicione uma entrada de roteamento que mapeie NextPDF\Symfony\Message\GeneratePdfMessage para um transporte em config/packages/messenger.yaml e, em seguida, execute um worker (php bin/console messenger:consume <transport>).
• Builder não está no locator — o handler obtém o builder de um locator PHP Standards Recommendation 11 (PSR-11) pelo respectivo id em formato class-string. Um identificador de container é uma string que identifica uma entrada de modo único (PSR-11 §1.1.2). Se a classe do builder não estiver registrada no locator, o handler lança uma RuntimeException informando que o builder configurado deve implementar PdfBuilderInterface. Registre o builder e, em seguida, referencie-o a partir do locator.

Inspecione o roteamento e o locator:

php bin/console debug:messenger
php bin/console debug:container --tag=container.service_locator

Mensagem rejeitada no despacho com InvalidArgumentException

Sintoma: construir GeneratePdfMessage lança uma InvalidArgumentException.

Causa: o data transfer object (DTO) da mensagem valida suas entradas. As regras de rejeição verificadas são:

• caminho de saída vazio, ou um que contenha um byte nulo;
• um esquema de stream-wrapper (por exemplo php://...);
• um segmento de path traversal .. (separadores POSIX ou Windows);
• um caminho de saída que não termine em .pdf (sem diferenciar maiúsculas de minúsculas);
• um builderClass que não seja um nome de classe sintaticamente válido.

Resolução: passe um caminho de sistema de arquivos absoluto que termine em .pdf e um nome de classe de builder real totalmente qualificado.

Um documento carrega dados obsoletos

Sintoma: um PDF gerado inclui conteúdo de uma requisição anterior.

Causa: um worker de longa duração manteve uma instância de Document entre requisições. O serviço de documento é non-shared exatamente para evitar isso.

Resolução: chame PdfFactory::create() dentro do método no escopo da requisição. Nunca armazene o documento retornado em um serviço compartilhado.

Referência de comandos de diagnóstico

php bin/console debug:container nextpdf          # bundle services
php bin/console debug:config nextpdf             # merged configuration
php bin/console debug:container --show-private   # internal definitions
php bin/console debug:messenger                  # message routing
php bin/console messenger:consume <t> -vv        # verbose consume

Conformidade

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

Especificação	Cláusula	reference_id	Afirmação
PSR-11	psr_11_container#1.1.2.p4		Contrato de identificador de has()/get() do container

Veja também

• /integrations/symfony/install/ — instalação e registro.
• /integrations/symfony/configuration/ — schema completo e restrições.
• /integrations/symfony/boot-and-discovery/ — descoberta e sequência de inicialização.
• /integrations/symfony/security-and-operations/ — cabeçalhos de segurança e validação de caminho.