Referência da API de compatibilidade com TCPDF

Visão geral

O pacote nextpdf/compat-legacy expõe uma classe principal, NextPDF\Compat\Tcpdf\TCPDF. Ela espelha a interface de programação de aplicações (API) pública do TCPDF 6.x, mas renderiza com o motor moderno do NextPDF. O pacote também inclui uma pequena superfície de suporte: LegacyBootstrap para aliases globais de classe, a superfície de configuração AdaptationConfig/LegacyDefaults, classes internas de bridge para saída, construção, cor, unidades e formatos de página, além de exceções de compatibilidade. Use-o como auxiliar de migração, não como dependência permanente. A tabela de cobertura de métodos é a fonte do status completo dos métodos legados. Esta página documenta apenas as superfícies das quais o código da aplicação deve depender intencionalmente.

Comece por aqui: Se este pacote é novo para você, construa NextPDF\Compat\Tcpdf\TCPDF, faça as chamadas habituais do TCPDF (AddPage(), SetFont(), Cell()) e termine com Output($name, $dest). Essa classe é o ponto de entrada para quase tudo a seguir. Para pontos de partida executáveis, consulte Tarefas comuns.

Tarefas comuns

Estas são as tarefas do pacote que você usará com mais frequência. Cada bloco é verificado em relação ao código-fonte do adaptador e roda como está.

Produza um arquivo Portable Document Format (PDF) com chamadas TCPDF familiares e, em seguida, capture-o como string para uma fila, uma resposta HTTP ou armazenamento:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

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

$bytes = $pdf->Output('invoice.pdf', 'S');

O que faz: Cria um documento PDF 2.0 por meio do adaptador no formato do TCPDF. Ele retorna os bytes brutos (%PDF...) porque o destino 'S' passa por OutputBridge até Document::getPdfData(), em vez de fazer echo, o que o torna seguro dentro de um worker ou controller.

Registre os aliases globais uma vez na inicialização para executar código new \TCPDF(...) existente sem editar o código-fonte:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

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

O que faz: enableAliases() registra de forma idempotente \TCPDF (e os auxiliares \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) somente quando esses nomes ainda não estão definidos. Assim, o código legado inalterado roda sobre o adaptador.

Audite uma migração expondo cada parâmetro do TCPDF que o adaptador descartaria silenciosamente:

<?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('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter
}

O que faz: Com setStrictMode(true), uma chamada que não consegue reproduzir o comportamento do TCPDF lança TcpdfNotImplementedException e nomeia cada parâmetro ignorado. Isso transforma a degradação silenciosa em uma lista de trabalho de migração. Execute apenas durante uma etapa de auditoria, nunca em produção.

Adaptador principal

Esta tabela é a superfície canônica do adaptador. Use-a para encontrar a classe que você instancia (TCPDF), seus métodos de modo estrito e de escape, e o contrato que ela implementa.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
NextPDF\Compat\Tcpdf\TCPDF	Os parâmetros do construtor seguem o formato legado do TCPDF por meio de ConstructorBridge.	Cria um adaptador apoiado por um documento do NextPDF.	TCPDF	Exceções de validação do construtor ou de recurso não suportado.	Use durante a migração, não para código nativo novo do NextPDF.
TCPDF::getDocument()	nenhum.	Retorna o documento NextPDF subjacente.	NextPDF\Core\Document	nenhuma esperada.	Use como válvula de escape para código de migração que precisa mesclar chamadas legadas e nativas.
TCPDF::getUnitConverter()	nenhum.	Retorna o conversor criado a partir da unidade legada.	UnitConverter	nenhuma esperada.	Use para diagnósticos de migração, não em código normal de aplicação.
TCPDF::setStrictMode(bool $enabled)	Sinalizador de modo estrito.	Ativa ou desativa a falha explícita para comportamento de compatibilidade não suportado.	static	nenhuma esperada.	Mantenha ativado durante auditorias de migração.
TCPDF::isStrictMode()	nenhum.	Retorna o sinalizador de modo estrito atual.	bool	nenhuma esperada.	Útil em asserts de teste.
TCPDF métodos legados	Varia conforme o método.	Os métodos suportados são mapeados para chamadas do documento de núcleo; os métodos não suportados falham explicitamente.	Varia conforme o método.	TcpdfNotImplementedException ou UnsupportedFeatureException.	Verifique a cobertura de métodos antes de depender de um método.
CompatAdapterInterface::getDocument()	nenhum.	Método de contrato implementado por TCPDF.	Document	nenhuma esperada.	Permite que ferramentas acessem o documento nativo.
CompatAdapterInterface::Output(string $name = '', string $dest = '')	Nome do arquivo e destino legado.	Delega ao bridge de saída.	string	Erros de escrita do núcleo ou de destino não suportado.	Espelha a saída legada do TCPDF; o TCPDF::Output concreto fornece os padrões 'doc.pdf'/'I'.

Grupos de métodos legados

Esta tabela mapeia as famílias de métodos do TCPDF cobertas pelo adaptador. Use-a para localizar uma chamada legada antes de verificar seu status exato na cobertura de métodos.

Grupo	Símbolos representativos	Comportamento padrão	Notas
Ciclo de vida e saída	Open(), Close(), Output(), getPDFData()	Mantém um ciclo de vida de documento no formato do TCPDF sobre um documento nativo.	Prefira as APIs nativas de saída após a migração.
Metadados	SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator()	Mapeia os setters de metadados para o documento subjacente.	Mantenha a normalização de metadados no código da aplicação.
Páginas e posicionamento	AddPage(), setPage(), lastPage(), GetX(), SetXY()	Converte unidades e coordenadas legadas em operações nativas de página.	Verifique visualmente o posicionamento absoluto após a migração.
Margens e layout	SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins()	Armazena o estado de compatibilidade e mapeia os valores suportados.	O comportamento complexo de quebra de página do TCPDF pode exigir revisão manual.
Fontes e texto	SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text()	Encaminha operações comuns de texto para as APIs nativas de fonte e texto.	Verifique o comportamento de CJK e de codificação com fontes de produção.
HTML	writeHTML(), writeHTMLCell(), fixHTMLCode()	Passa o HTML suportado para o pipeline HTML nativo.	O renderizador nativo não é um clone completo do HTML do TCPDF.
Imagens e desenho	Image(), Line(), Rect(), Circle(), SetDrawColor()	Mapeia operações gráficas suportadas por meio dos concerns do adaptador.	Formatos vetoriais ou especiais não suportados falham explicitamente.
Navegação e anotações	Bookmark(), AddLink(), SetLink(), Annotation()	Preserva chamadas de navegação comuns onde mapeadas.	Valide os outlines e links gerados.
Segurança e assinaturas	SetProtection(), setSignature(), setTimeStamp(), setUserRights()	Faz a ponte de chamadas legadas de segurança suportadas para recursos nativos.	Trate a saída criptográfica como um portão de verificação separado.
Formulários, templates, transformações	TextField(), startTemplate(), StartTransform(), Rotate(), Scale()	Implementa os subconjuntos suportados e falha de forma ruidosa para comportamento não suportado.	Audite cada chamada em relação à cobertura de métodos antes da implantação.

Bootstrap e configuração

Use esta tabela quando você conectar o adaptador a um caminho de inicialização da aplicação, registrar aliases globais ou escolher entre constantes legadas e o AdaptationConfig moderno.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
LegacyBootstrap::enableAliases()	nenhum.	Registra os aliases de compatibilidade uma vez.	void	Erros de autoload ou de ambiente.	Use somente quando o código legado espera que os nomes do TCPDF existam globalmente.
LegacyBootstrap::isRegistered()	nenhum.	Informa se os aliases foram registrados.	bool	nenhuma esperada.	Útil em testes de bootstrap.
LegacyBootstrap::resetForTesting()	nenhum.	Limpa o estado de registro para os testes.	void	nenhuma esperada.	Auxiliar apenas para testes.
AdaptationConfig	Sinalizadores do adaptador e controles de migração.	Usa os padrões do pacote quando omitido.	AdaptationConfig	Valores de opção inválidos.	Mantenha a configuração explícita durante auditorias de migração.
AdaptationConfig::fromLegacyConstants()	nenhum.	Lê constantes legadas conhecidas e cria um objeto de configuração.	AdaptationConfig	Valores de constante legada inválidos.	Auxiliar de transição para grandes aplicações legadas.
LegacyDefaults	nenhum.	Fornece valores legados padrão.	Valores padrão.	nenhuma esperada.	Local central para os padrões de compatibilidade.

Bridges e auxiliares

Estas classes internas de conversão movem o adaptador. Use esta tabela quando você contribuir com a cobertura do adaptador ou diagnosticar como um argumento legado foi traduzido. Para o código de aplicação do dia a dia, prefira a superfície pública do adaptador.

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
ConstructorBridge	Lista de argumentos do construtor legado.	Normaliza opções legadas na configuração do NextPDF.	Dados do construtor.	Valores de argumento legado inválidos.	Usado internamente pelo adaptador.
CellParameterAdapter	Parâmetros de célula do TCPDF.	Mapeia argumentos posicionais legados para opções de layout de texto do núcleo.	Parâmetros adaptados.	Dimensões ou alinhamento inválidos.	Prefira os métodos nativos do núcleo em código novo.
OutputBridge::dispatch(Document $document, string $filename, string $dest)	Documento nativo, nome do arquivo e destino legado.	Mapeia o comportamento de inline/download/salvar para as APIs de saída do NextPDF.	string	Erros de escrita do núcleo; destino não suportado.	Valide os nomes de arquivo e as raízes de armazenamento antes da saída.
OutputBridge::resolveDestination(string $dest)	Código de destino legado.	Converte o destino em um destino de saída nativo.	OutputDestination	Erros de destino não suportado.	Mantém o mapeamento de destino centralizado.
ColorTranslator	Argumentos de cor do TCPDF.	Normaliza as formas de cor legadas.	Valor de cor do núcleo.	Valores de cor inválidos.	Usado pelos concerns de cor e desenho.
PageFormatResolver	Entrada de formato de página legado.	Mapeia nomes conhecidos para tamanhos de página do núcleo.	Valor de formato de página.	Formato desconhecido.	Use tamanhos de página nativos explícitos após a migração.
UnitConverter	Valores e unidades de medida legados.	Converte para unidades do núcleo.	Valor numérico.	Unidade inválida.	Ajuda a preservar o comportamento de layout legado.

Exceções

Use esta tabela quando uma chamada de migração falhar de forma ruidosa. Ela separa as falhas “não implementado” das “conhecidas, mas não suportadas” e mostra o caminho de recuperação.

Símbolo	Significado	Recuperação
TcpdfNotImplementedException	O adaptador intencionalmente não implementa o método legado solicitado.	Substitua a chamada pela API nativa do NextPDF ou remova a dependência.
TcpdfNotImplementedException::forSilentIgnore()	Uma chamada legada teria sido ignorada antes, mas agora é exposta para dar clareza à migração.	Decida se o comportamento explícito de no-op é aceitável.
TcpdfNotImplementedException::forUnimplemented()	Uma chamada legada não tem caminho de adaptador implementado.	Substitua a chamada ou isole-a atrás de código de migração.
UnsupportedFeatureException	O recurso legado é conhecido, mas não suportado dentro da fronteira do adaptador.	Consulte a orientação de migração e isole o recurso atrás de um adaptador da aplicação.
UnsupportedFeatureException::forMethod()	Cria um erro de recurso não suportado específico de método.	Use em contribuições de compatibilidade para preservar mensagens de falha consistentes.

Notas de desenvolvimento

• Trate o adaptador como uma ferramenta de migração. O código novo deve mirar diretamente nas APIs do núcleo do NextPDF.
• O comportamento não suportado deve falhar de forma ruidosa. Não capture exceções de compatibilidade nem continue com um documento parcial, a menos que a aplicação aceite explicitamente esse risco.
• Mantenha as alterações de migração pequenas e verifique cada método legado em relação à tabela de cobertura.