Guia do desenvolvedor para compatibilidade com TCPDF

Em resumo

O adaptador de compatibilidade é uma camada de migração. Ele torna o comportamento legado visível em vez de ocultá-lo. Use-o para manter a aplicação em funcionamento enquanto você move os caminhos de alto valor para as APIs nativas do NextPDF.

Use este guia ao manter código legado no formato do TCPDF, adicionar cobertura ao adaptador ou planejar uma migração gradual para as APIs nativas do NextPDF.

Limite arquitetural

Camada	Pertence a	Responsabilidade	Não coloque aqui
Aplicação legada	Aplicação	Mantém em funcionamento as chamadas existentes no formato do TCPDF durante a migração.	Novos recursos de PDF que devem usar as APIs nativas do NextPDF.
Camada do adaptador	nextpdf/compat-legacy	Expõe a classe no formato do TCPDF e o estado de compatibilidade compartilhado.	Grandes famílias de métodos ou lógica de conversão.
Traits de responsabilidade (concern)	nextpdf/compat-legacy	Agrupa famílias de métodos legados: texto, fontes, imagens, segurança, formulários, páginas.	Política de saída entre famílias.
Classes de ponte (bridge)	nextpdf/compat-legacy	Converte argumentos, destinos, cores, unidades e formatos legados.	Comportamento específico do negócio.
Motor principal (core)	nextpdf/nextpdf	Cria o documento nativo.	Promessas de compatibilidade com código legado.

Ciclo de vida em tempo de execução

Estágio	Comportamento	Ação do desenvolvedor
Inicialização (bootstrap)	Uma inicialização legada opcional expõe os nomes de compatibilidade.	Use-a apenas onde o código legado espera símbolos do TCPDF.
Construção	O adaptador mapeia os argumentos do construtor legado para a configuração do documento do core.	Mantenha as entradas do construtor estáveis durante a migração.
Chamada de método	Os métodos com suporte são mapeados para o comportamento do NextPDF por meio de traits de responsabilidade e pontes.	Verifique a cobertura de métodos antes de presumir paridade.
Recurso sem suporte	O adaptador lança exceções de compatibilidade explícitas para comportamento sem suporte.	Substitua a chamada ou isole-a por trás do código da aplicação.
Saída	A ponte de saída mapeia o comportamento de destino legado para a saída do NextPDF.	Valide os nomes de arquivo e as raízes de armazenamento.

Inventário de migração

Comece coletando todas as chamadas de método do TCPDF na aplicação. Classifique cada chamada antes de alterar o comportamento.

Classificação	Significado	Ação
Método do adaptador com suporte	O método está documentado como suportado e tem testes.	Mantenha-o temporariamente e migre-o ao trabalhar nessa área.
Método do adaptador parcial	O método existe, mas o comportamento não corresponde totalmente ao TCPDF legado.	Adicione testes de fixture e valide a saída manualmente.
Método explicitamente sem suporte	O adaptador lança uma exceção de compatibilidade.	Substitua-o por NextPDF nativo ou remova o recurso.
Wrapper específico do negócio	A aplicação já encapsula as chamadas do TCPDF.	Migre primeiro a lógica interna do wrapper.
Chamada sensível à conformidade	Fluxo de assinatura, criptografia, marcação (tagging), PDF/A, acessibilidade ou faturamento.	Migre para as APIs nativas do NextPDF com verificação dedicada.

Padrão de contribuição para o adaptador

Adicione suporte de compatibilidade na menor família de métodos que detém aquele comportamento.

Tipo de alteração	Onde implementar	Teste obrigatório
Método de saída de texto	Concerns\AdaptsTextOutput ou a trait de fonte.	Fixture legado e asserção da saída nativa.
Método de página ou margem	Trait de página, posicionamento ou margem.	Teste de conversão de coordenadas e estado de página.
Método de imagem ou desenho	Trait de imagem, desenho, cor ou gradiente.	Teste de validação de entrada e de saída visual/estrutural.
Destino de saída	OutputBridge.	Teste de mapeamento de destino e de caminho inseguro.
Recurso sem suporte	Fábrica de exceção ou tabela de cobertura de métodos.	Teste de tipo de exceção e de mensagem.

Não coloque um método grande diretamente na camada do adaptador quando uma trait de responsabilidade detém a família.

Padrão de migração nativa

Use o adaptador para estabilizar o código legado e, em seguida, mova os fluxos de trabalho estáveis para as APIs nativas.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Trate a migração como uma sequência de pequenos movimentos comportamentais. Uma página ainda pode usar o adaptador enquanto uma seção de alto risco é movida para as APIs nativas.

Pontos de extensão

Ponto de extensão	Use-o para	Restrição
AdaptationConfig	Controle o comportamento do adaptador durante a migração.	Mantenha os padrões explícitos e revisados.
Traits de responsabilidade (concern)	Agrupe famílias de métodos como texto, formulários, imagens ou segurança.	Adicione métodos à trait de responsabilidade apropriada, não à camada do adaptador.
Classes de ponte (bridge)	Converta os formatos de argumento legados em valores do core.	Cubra o comportamento da ponte com testes de migração.
CompatAdapterInterface	Abstração no nível do adaptador para ferramentas.	Não use como substituto dos contratos nativos do core em código novo.
Tabela de cobertura de métodos	Registro de suporte voltado ao desenvolvedor.	Atualize-a quando o status de suporte mudar.

Fluxo de trabalho de migração

1. Instale o adaptador e execute o conjunto de testes legado sem alterações.
2. Abra a cobertura de métodos e classifique cada método chamado.
3. Substitua primeiro os métodos sem suporte.
4. Mova os caminhos de alto volume ou sensíveis à conformidade para as APIs nativas do core.
5. Adicione cobertura de fixture para cada família de métodos migrada.
6. Remova os aliases de inicialização quando nenhum ponto de entrada da aplicação depender deles.

Tratamento de falhas

Falha	Onde deve ser tratada	Resposta recomendada
Método sem suporte	Exceção do adaptador.	Substitua a chamada ou isole-a por trás de um adaptador da aplicação.
Paridade parcial de layout	Testes de migração e revisão visual.	Documente a diferença aceita antes da implantação.
Destino de saída inseguro	OutputBridge e política de armazenamento da aplicação.	Rejeite caminhos inseguros e prefira as APIs nativas de saída.
Incompatibilidade de recurso de segurança	Plano de migração nativa.	Não entregue comportamento exclusivo de compatibilidade para saídas regulamentadas.
Colisão de alias de inicialização	Inicialização da aplicação.	Remova os aliases globais ou restrinja-os aos pontos de entrada legados.

Padrões seguros

Responsabilidade (concern)	Padrão	Quando substituir
Métodos sem suporte	Lançar exceção explícita.	Não enfraqueça isso em produção.
Padrões legados	Centralizados em LegacyDefaults.	Substitua apenas para comportamento de migração conhecido.
Mapeamento de saída	Passa por OutputBridge.	Use as APIs nativas de saída após a migração.
Fonte de cobertura	Página de cobertura de métodos e testes.	Execute as verificações de cobertura novamente após cada atualização do adaptador.
Modo estrito	Mantenha habilitado durante as auditorias de migração.	Desabilite apenas para uma janela de compatibilidade legada documentada.

Lista de verificação de testes

• Mantenha um fixture legado para cada família de métodos migrada.
• Adicione um teste nativo do NextPDF antes de substituir um método legado.
• Verifique se os métodos sem suporte lançam a exceção documentada.
• Compare a estrutura da saída quando a igualdade exata de bytes não for uma meta realista de migração.
• Execute as verificações de cobertura de métodos depois de adicionar ou alterar métodos do adaptador.
• Adicione testes de caminho de armazenamento para cada destino de saída que o código legado usa.