Solução de problemas do NextPDF no CodeIgniter 4

Visão geral

Cada sintoma abaixo corresponde a uma causa verificada no código-fonte do pacote ou do framework e vem acompanhado de uma correção concreta.

Descoberta e resolução

`Services::pdfDocument()` retorna `null`

Quando o CodeIgniter resolve um serviço, ele examina as classes Config\Services descobertas em busca de um método correspondente. Um retorno null significa que o CodeIgniter não descobriu a classe Services do pacote.

Confira estas causas e correções:

A descoberta automática está desativada. A aplicação que hospeda o pacote pode definir Config\Modules::$discoverInComposer = false. Se for o caso, adicione nextpdf/codeigniter a $composerPackages['only']. O CodeIgniter só examina os pacotes do Composer quando essa flag é true.
O autoloader está desatualizado. O Composer mapeia o prefixo de namespace NextPDF\CodeIgniter\ para o diretório base correspondente. Um classmap desatualizado oculta a classe (PSR-4 §x1.x3). Execute composer dump-autoload.
A lista $aliases foi reduzida. A descoberta é executada apenas para as entradas em Config\Modules::$aliases. O pacote precisa de services e, para os helpers, também de registrars. Restaure ambas as entradas.

`pdf()` ou `pdf_document()` está indefinido

Os helpers são carregados por dois caminhos: a entrada de autoload files do Composer do pacote e o Registrar do pacote. Um erro de função indefinida significa que a entrada files não foi carregada.

Execute composer dump-autoload para reconstruir a lista de autoload files.
Confirme que nextpdf/codeigniter aparece em vendor/composer/autoload_files.php.
Se você precisar de uma solução alternativa, chame Services::pdf(false) ou Services::pdfDocument(false) diretamente. Os helpers são wrappers finos em torno dessas chamadas.

Configuração

`.env`: as substituições são ignoradas

Para resolver uma substituição, o BaseConfig usa o nome curto da classe em minúsculas como prefixo. Como a classe é NextPdf, o prefixo é nextpdf. Não é nextPdf nem NextPdf.

Use nextpdf.fontsPath, não nextPdf.fontsPath.
Para uma chave aninhada, use um ponto: nextpdf.signature.certificate.
A forma totalmente qualificada NextPDF\CodeIgniter\Config\NextPdf.fontsPath também funciona.

Um array de configuração inteiro reverte para os padrões

Quando você estende a classe NextPdf e atribui um array parcial, o CodeIgniter substitui o array inteiro. Forneça todas as chaves do array que você substituir. Para ver um exemplo com o array completo, consulte /integrations/codeigniter/configuration/.

Erros de tempo de execução

`RuntimeException: NextPDF requires the ext-… PHP extension`

O registro de fontes valida mbstring e zlib uma vez por processo. Ele gera esse erro com o nome da extensão ausente. Instale ou ative a extensão indicada no PHP em execução e, em seguida, reinicie o worker ou o pool do PHP FastCGI Process Manager (PHP-FPM).

`RuntimeException: NextPdf fontsPath contains invalid characters`

O registro de fontes rejeita um fontsPath que contenha um stream wrapper (://) ou um byte nulo. Defina fontsPath como um caminho simples do sistema de arquivos. Não aponte esse valor para um caminho com wrapper como php://, phar:// ou similar.

Problemas de resposta

O nome do arquivo parece incorreto no download

PdfResponse sanitiza os nomes de arquivo. Espere este comportamento verificado:

Um nome de arquivo vazio ou contendo apenas espaços em branco torna-se document.pdf.
Um nome sem a extensão .pdf (ou .PDF) recebe .pdf acrescentado ao final. Uma extensão .PDF existente é preservada como está.
Um nome com caracteres não ASCII produz um fallback ASCII e um parâmetro RFC 5987 filename*=UTF-8''…, de modo que navegadores modernos exibem o nome original. Isso é esperado, não é um bug.
Separadores de caminho, bytes nulos e caracteres de retorno de carro e avanço de linha (CR/LF) são removidos.

Resposta sem cabeçalhos de segurança

Toda PdfResponse inclui X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, X-Robots-Tag e Referrer-Policy. Se eles estiverem ausentes no cliente, um proxy ou a aplicação está removendo ou sobrescrevendo esses cabeçalhos mais adiante no fluxo. Inspecione a resposta tanto antes quanto depois do proxy reverso.

Fila

`QueueException` ao enfileirar o job

A fila compara o nome do job enfileirado com as chaves em Config\Queue::$jobHandlers e rejeita qualquer nome que não esteja registrado. Registre o job sob uma chave de nome e, em seguida, enfileire esse nome:

public array $jobHandlers = ['generate-pdf' => GeneratePdfJob::class];

// dispatch
\service('queue')->push('pdf-queue', 'generate-pdf', [...]);

Enfileirar GeneratePdfJob::class como nome do job falha. O segundo argumento é uma chave de nome, não uma string de classe.

`InvalidArgumentException` proveniente do job

O job valida o payload antes de realizar qualquer trabalho. Estes casos de rejeição verificados retornam estes fragmentos de mensagem:

Causa	Fragmento de mensagem
`builder` ausente, vazio ou não é uma string	`non-empty static callable string`
`builder` fora de `App\PdfBuilders`	`not allowed`
`builder` corresponde ao padrão, mas não é chamável	`not a valid callable`
`outputPath` ausente ou vazio	`non-empty string`
`outputPath` fora de `WRITEPATH/pdfs/`	`outside of allowed directory`
`outputPath` que não termina em `.pdf`	`must end with .pdf`

Corrija o payload para que o builder seja um callable estático App\PdfBuilders\<Class>::<method>. Verifique se o caminho de saída resolve para dentro de WRITEPATH/pdfs/ com a extensão .pdf.

`class … BaseJob not found`

Como codeigniter4/queue é uma dependência apenas de desenvolvimento do pacote, a aplicação que executa workers deve declará-la diretamente:

composer require codeigniter4/queue

Diagnósticos

composer show nextpdf/codeigniter — confirme que o Composer conseguiu resolver o pacote.
composer dump-autoload — reconstrói a descoberta e a lista de autoload dos helpers.
php spark routes — confirme que as rotas de PDF estão registradas.
Para a verificação de descoberta mais rápida, use um controller que chame Services::pdfDocument(false) e verifique que o resultado é um Document.

Conformidade

Mapeamento de classe para caminho — relevante para falhas de descoberta (PSR-4 Autoloader §x1.x3).

Veja também

/integrations/codeigniter/install/ — requisitos para a descoberta.
/integrations/codeigniter/configuration/ — o prefixo .env e a regra de substituição de array.
/integrations/codeigniter/production-usage/ — registro correto da fila.
/integrations/codeigniter/boot-and-discovery/ — a sequência de descoberta.