Guia rápido do compat-legacy

Visão geral

Esta página orienta você do pacote instalado até um PDF finalizado e, depois, até a auditoria em modo estrito que você executa antes da migração. Cada bloco de código corresponde ao comportamento verificado pela suíte de testes do pacote; por isso, a saída mostrada aqui é exatamente a saída que os testes validam.

Antes de começar

Instale o pacote e confirme a integração com o engine seguindo /integrations/tcpdf-compat/install/. Você precisa do PHP 8.4, e nextpdf/core ^3.0 deve estar resolvido.

1. Produza o primeiro documento

Altere o import e mantenha as chamadas no estilo TCPDF. Essa é exatamente a superfície verificada por tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php.

examples/quickstart-first.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Execute:

php examples/quickstart-first.php

O arquivo quickstart.pdf é um PDF 2.0 válido. A suíte de testes confirma que a saída correspondente em string começa com %PDF para os destinos S, F e E e para getPDFData().

Destinos de saída

Output($name, $dest) mapeia os códigos de destino do TCPDF por meio de uma ponte de saída segura. A suíte de testes cobre este comportamento:

$dest	Comportamento	Retorna
'S'	Retorna o PDF como string	bytes do PDF (%PDF…)
'F'	Grava o PDF no caminho informado	string vazia
'E'	Retorna um corpo MIME em base64	um Content-Type: application/pdf em um bloco
'I'	Inline (padrão)	conforme a ponte de saída
'D'	Download	conforme a ponte de saída

Ao contrário do TCPDF legado, Output() não imprime diretamente no buffer de saída ativo. Você pode chamá-lo com segurança em um worker de fila ou em um handler HTTP que controla a própria resposta. Veja /integrations/tcpdf-compat/production-usage/.

2. Execute código TCPDF existente sem alterações

Para uma migração real, comece executando o código existente, alterando apenas o import ou o alias. Se a base de código chama new \TCPDF(...) no namespace global, habilite os aliases opcionais uma vez na inicialização (descrito em /integrations/tcpdf-compat/boot-and-discovery/):

examples/quickstart-alias.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Legacy code now resolves \TCPDF to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/aliased.pdf', 'F');

LegacyBootstrap::enableAliases() é idempotente. Ele registra \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS e \TCPDF_IMAGES apenas quando essas classes ainda não existem. O teste do pacote tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php confirma que os aliases são registrados, que a chamada é idempotente e que new \TCPDF() é uma instância do adaptador. Não habilite os aliases se a biblioteca TCPDF real estiver carregada no mesmo processo; veja /integrations/tcpdf-compat/troubleshooting/.

3. Audite com o modo estrito

Esta etapa torna a migração mais segura. Com o modo estrito desligado (o padrão), os métodos que não conseguem reproduzir o comportamento do TCPDF degradam silenciosamente. Com o modo estrito ligado, eles lançam TcpdfNotImplementedException com a lista exata dos parâmetros ignorados. Execute isso em uma rodada de auditoria dedicada, nunca em produção.

examples/quickstart-strict-audit.php

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

O teste do pacote tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php confirma que exatamente esta chamada lança uma exceção no modo estrito e permanece silenciosa no modo padrão, e que a mensagem contém o nome do método e os parâmetros ignorados. Use as exceções coletadas como a lista de trabalho da migração — veja /integrations/tcpdf-compat/migration/.

4. Acesse a API moderna quando precisar

Cada instância do adaptador expõe o documento do engine subjacente. Use-o para chamar métodos modernos do NextPDF sem equivalente no TCPDF:

examples/quickstart-escape-hatch.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() retorna o NextPDF\Core\Document que o adaptador encapsula. Esse é o caminho de saída recomendado: migre os pontos de chamada para a API moderna um de cada vez, até poder remover o adaptador.

Diferenças de comportamento esperadas de imediato

• MultiCell() retorna 1, não a contagem de células renderizadas. Código que toma caminhos diferentes com base no valor de retorno de MultiCell() precisa de ajuste.
• Error() lança RuntimeException em vez de chamar die(). Código que dependia do encerramento do processo deve capturar a exceção.
• Os bytes exatos do PDF diferem da saída do TCPDF. Atualize a baseline das asserções de teste em nível de bytes para que elas verifiquem o conteúdo renderizado.

A lista completa por método está em /integrations/tcpdf-compat/method-coverage/.

Próximos passos

• /integrations/tcpdf-compat/migration/ — a estratégia completa de migração arquivo por arquivo.
• /integrations/tcpdf-compat/configuration/ — modo estrito, padrões e o objeto de configuração moderno.
• /integrations/tcpdf-compat/production-usage/ — workers, buffers de saída e desempenho.
• /integrations/tcpdf-compat/security-and-operations/ — postura de criptografia e assinatura.

Veja também

• tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — referência do comportamento de saída
• tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — referência do modo estrito
• docs/TCPDF_COVERAGE.md — matriz de cobertura canônica