Solução de problemas do compat-legacy

Visão geral

A maioria dos problemas de migração se enquadra em um pequeno conjunto de padrões. Cada item abaixo lista o sintoma, a causa e a correção. Se tiver dúvida sobre um método específico, consulte /integrations/tcpdf-compat/method-coverage/ e a matriz oficial no repositório docs/TCPDF_COVERAGE.md.

O processo antes parava em um erro de PDF; agora uma exceção é propagada

Sintoma. O código que antes parava em uma renderização inválida agora lança uma RuntimeException não capturada, e a requisição ou o job reporta erro.

Causa. As chamadas Error() do TCPDF legado chamam die(). Em vez disso, o adaptador lança RuntimeException de propósito, para que as falhas sejam observáveis.

Correção. Envolva os pontos de entrada de renderização em try/catch e mapeie a exceção para o contrato de erro que você usa. Não restaure o comportamento de die(). Consulte /integrations/tcpdf-compat/production-usage/ § Tratamento de falhas.

`new \TCPDF()` ainda resolve para a biblioteca TCPDF real

Sintoma. Você ativou LegacyBootstrap::enableAliases(), mas a saída ainda parece vir do TCPDF legado, ou o comportamento não mudou.

Causa. enableAliases() registra um alias apenas quando ainda não existe nenhuma classe com aquele nome. Se tecnickcom/tcpdf continuar carregável por autoload e a classe \TCPDF dele for carregada primeiro, o alias será ignorado, e o código continuará usando o TCPDF legado.

Correção. Durante a migração, use importações explícitas por arquivo (use NextPDF\Compat\Tcpdf\TCPDF;) para que cada ponto de chamada fique inequívoco. Remova tecnickcom/tcpdf depois que a auditoria passar (consulte /integrations/tcpdf-compat/migration/ Estágio 5). Não execute as duas bibliotecas com aliases globais ativados no mesmo processo.

Um método “funciona”, mas o parâmetro que passei é ignorado

Sintoma. Uma chamada é bem-sucedida e produz um arquivo Portable Document Format (PDF), mas uma opção que você passou (link da imagem, alinhamento, pontos por polegada (DPI), cor do bookmark, …) não surte efeito.

Causa. O método está no conjunto dos itens ignorados silenciosamente. Ele aceita o parâmetro por compatibilidade de código-fonte e, em seguida, o descarta. Esse é um comportamento documentado, não um bug; consulte /integrations/tcpdf-compat/method-coverage/ §2.

Correção. Execute uma auditoria em modo estrito para encontrar todas as chamadas desse tipo:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;
use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->setStrictMode(true);
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);

try {
    $pdf->Image('logo.png', 10, 10, 50, 0, '', 'https://example.com');
} catch (TcpdfNotImplementedException $e) {
    // Message lists every ignored parameter and a migration hint.
    echo $e->getMessage(), "\n";
}

Em seguida, remova o parâmetro ou expresse-o novamente pela API moderna ($pdf->getDocument()), conforme mostrado em /integrations/tcpdf-compat/migration/ Estágio 4.

`MultiCell()` sempre retorna 1

Sintoma. O código que desvia o fluxo com base no valor de retorno de MultiCell() (por exemplo, para calcular a altura utilizada ou a contagem de linhas) se comporta incorretamente.

Causa. O MultiCell() do adaptador retorna o valor de compatibilidade 1, não a contagem de células renderizadas nem a contagem de linhas. Write() retorna 0 de forma semelhante.

Correção. Não desvie o fluxo com base nesses valores de retorno. Se você precisar da altura renderizada, calcule-a a partir de getStringHeight() / getNumLines() ou mova essa lógica para a API moderna.

`setPDFVersion('1.4')` não produziu um arquivo PDF 1.4

Sintoma. Você pediu uma versão mais antiga de PDF, mas a saída continua sendo PDF 2.0.

Causa. O adaptador sempre gera PDF 2.0 (ISO 32000-2). setPDFVersion() está no conjunto dos itens não aplicáveis; o adaptador emite um aviso e continua.

Correção. Remova a chamada. Se um consumidor downstream exigir uma versão mais antiga de PDF, resolva esse requisito separadamente; o adaptador não consegue gerar uma versão de destino anterior.

`setSignature()` não fez nada — o PDF não está assinado

Sintoma. Você chamou setSignature() com um certificado, mas o PDF de saída não tem assinatura.

Causa. O motor principal não implementa setSignature() por meio deste adaptador. No modo padrão, é uma operação sem efeito (no-op); no modo estrito, lança uma exceção.

Correção. A assinatura requer uma edição comercial do NextPDF e a API de assinatura moderna. Consulte /integrations/tcpdf-compat/security-and-operations/ § Assinaturas digitais. Não espere que a chamada legada setSignature() assine o documento.

`Output()` corrompeu minha resposta HTTP ou a saída do worker

Sintoma. Bytes de PDF aparecem em uma resposta Hypertext Transfer Protocol (HTTP), ou um log de worker fica contaminado com bytes de PDF.

Causa. Você usou um destino de saída que escreve no caminho de saída (I/D) enquanto você mesmo controla a resposta. O adaptador não escreve diretamente no seu buffer como o TCPDF legado faz, mas I/D ainda acionam a saída do motor.

Correção. Em workers e handlers que você controla, use Output($path, 'F') para gravar um arquivo ou Output($name, 'S') para obter os bytes e emiti-los você mesmo. tests/Unit/Compat/Tcpdf/Bridge/OutputBridgeTest.php verifica que o mapeamento de destino não diferencia maiúsculas de minúsculas e remove espaços em branco nas extremidades:

Código	Retorna	Efeito colateral
`S`	Bytes de PDF (`%PDF…`)	nenhum
`F`	string vazia	grava arquivo
`E`	corpo MIME em base64	nenhum
`FI` / `FD`	string vazia	grava arquivo e, em seguida, saída do motor
`I` / `D` / desconhecido	string vazia	saída do motor (inline/download)

Asserções de PDF byte a byte falham após a troca

Sintoma. Testes de snapshot que comparam bytes brutos de PDF falham em todos os lugares.

Causa. O motor usa uma implementação independente de PDF 2.0. Os métodos delegados produzem uma saída visualmente compatível, mas os bytes diferem. Isso é esperado.

Correção. Atualize a baseline dos testes para verificar o conteúdo renderizado (texto extraído), a estrutura (contagem de páginas, tamanho da página) ou uma verificação rápida (str_starts_with($bytes, '%PDF')). Consulte /integrations/tcpdf-compat/migration/ Estágio 4.

Uma constante legada `K_` / `PDF_` tem o valor errado

Sintoma. Um caminho personalizado ou um padrão que você definiu por meio de uma constante não está surtindo efeito.

Causa. O adaptador define uma constante automaticamente apenas se ela ainda não estiver definida, e faz isso durante a primeira construção. Se o seu define() for executado depois que o primeiro adaptador for construído, o padrão do adaptador já estará em vigor.

Correção. Defina todas as constantes personalizadas K_* / PDF_* no seu bootstrap, antes de qualquer instância do adaptador ser criada. Consulte /integrations/tcpdf-compat/configuration/ § Ordem de resolução da configuração.

Incompatibilidade de versão do motor na construção

Sintoma. A construção falha, ou o comportamento muda inesperadamente após uma atualização de dependência.

Causa. O adaptador requer nextpdf/core ^3.0. Uma versão do core resolvida fora desse intervalo não é compatível.

Correção. Execute composer show nextpdf/core e fixe o motor em ^3.0. Consulte /integrations/tcpdf-compat/install/ § Verificar a versão do motor.

Referência rápida de diagnóstico

Pergunta	Onde procurar
O que o método X realmente faz aqui?	/integrations/tcpdf-compat/method-coverage/, `docs/TCPDF_COVERAGE.md`
Quais das minhas chamadas perdem parâmetros?	Auditoria em modo estrito (esta página; /integrations/tcpdf-compat/migration/)
Por que o processo não parou no erro?	/integrations/tcpdf-compat/security-and-operations/ § Comportamentos reforçados
Por que a saída não está assinada / não é PDF/A?	/integrations/tcpdf-compat/security-and-operations/
Conflito entre alias e importação explícita	Esta página; /integrations/tcpdf-compat/boot-and-discovery/

Veja também

/integrations/tcpdf-compat/migration/ — migração em estágios que evita a maioria dos problemas acima
/integrations/tcpdf-compat/method-coverage/ — referência de comportamento por método
/integrations/tcpdf-compat/boot-and-discovery/ — registro de aliases e prevenção de conflitos
docs/TCPDF_COVERAGE.md — matriz oficial de cobertura