Visão geral do NextPDF compat-legacy

Visão geral rápida

nextpdf/compat-legacy é uma alternativa compatível com o TCPDF: uma camada de compatibilidade que expõe a API pública do TCPDF 6.x no motor Portable Document Format (PDF) 2.0 do NextPDF. Ela tem uma única função: ajudar o código que já depende do TCPDF 6.x a rodar no motor NextPDF sem reescrita, para que você migre arquivo por arquivo, em vez de tudo de uma vez.

Ela não é um fork do TCPDF, nem um clone comportamental garantido. É uma implementação independente que mantém as assinaturas de chamada do TCPDF. A formulação precisa é esta: ela cobre 94 de cerca de 120 métodos do TCPDF 6.x analisados por delegação direta, e os métodos restantes apresentam diferenças comportamentais documentadas (consulte /integrations/tcpdf-compat/method-coverage/).

O que ela é

Um auxílio de migração. O pacote pertence à família compat do NextPDF. Ele ajuda você a deixar para trás uma biblioteca PDF legada; não foi concebido para se tornar uma dependência permanente. Trate-o como uma estrutura temporária que você remove à medida que adota a API moderna.
Um adaptador de superfície de API. Ele fornece o nome da classe do TCPDF, os nomes dos métodos, a ordem dos parâmetros e os valores padrão do TCPDF 6.2.13. Ele delega as chamadas a uma instância de NextPDF\Core\Document.
Uma implementação independente, de sala limpa. Este pacote não copia nem traduz código-fonte do TCPDF, artefatos de compilação, dados de fontes ou qualquer outra expressão protegida por direitos autorais. Ele usa o nome TCPDF apenas para identificar a interoperabilidade. A declaração canônica está no arquivo NOTICE do pacote.

O que ela não é

Ela não é uma “substituição direta” com saída idêntica byte a byte. Para métodos delegados, o resultado visível é compatível, mas os bytes do PDF renderizado diferem porque a execução passa por uma implementação PDF 2.0 separada e independente.
Ela não é “100% compatível com o TCPDF”. Há um conjunto definido de métodos que aceita parâmetros legados que o motor não respeita ou que simplesmente não faz nada. Esses métodos são enumerados e testados — consulte /integrations/tcpdf-compat/method-coverage/.
Ela não é, por si só, um produto de assinatura nem de arquivamento. Assinaturas digitais e conformidade de arquivamento PDF/A são restritas a uma edição comercial do NextPDF. Esta documentação não faz nenhuma afirmação de assinatura certificada, garantida ou juridicamente válida.

Por que migrar por meio de uma camada de compatibilidade

Reescrever cada chamada do TCPDF em uma aplicação grande traz riscos e dificulta entregas incrementais. A camada de compatibilidade permite que você:

Substitua a dependência e, em seguida, execute a suíte de testes existente para descobrir o que funciona sem alterações.
Use o modo estrito como auditoria que lista cada ponto em que o comportamento do TCPDF não pode ser reproduzido com exatidão.
Migre esses pontos de chamada para a API moderna do NextPDF um de cada vez, para que a aplicação permaneça pronta para entrega o tempo todo.

O estado final é a API moderna do NextPDF\Core\Document, com a camada de compatibilidade removida. Consulte /integrations/tcpdf-compat/migration/ para a estratégia completa.

O que você ganha no motor NextPDF

Quando o adaptador delega uma chamada do TCPDF, ela é executada em um motor PDF 2.0 (ISO 32000-2), com a criptografia Advanced Encryption Standard (AES)-256 do manipulador padrão disponível e segurança de tipos PHPStan Level 10 em todo o adaptador. A saída é sempre gravada como PDF 2.0; o adaptador não pode direcionar a saída para versões anteriores do PDF (consulte /integrations/tcpdf-compat/method-coverage/ §4).

O adaptador torna mais seguros vários comportamentos históricos do TCPDF 6.2.13:

Comportamento legado	Comportamento do adaptador
`Error()` chama `die()` e encerra o processo silenciosamente	`Error()` lança `RuntimeException` — observável e capturável
Método HTML que podia executar PHP a partir da marcação	Essa válvula de escape está desativada — a marcação não pode disparar a execução de PHP
`Output()` emite a saída diretamente e pode corromper os buffers de saída dos workers	A saída passa por uma ponte de destino segura
Recursão de header/footer sem proteção	Protegida contra recursão

Escopo e edições

A camada de compatibilidade é distribuída na edição core (nextpdf/compat-legacy, que exige nextpdf/core ^3.0). A criptografia por meio do manipulador padrão está disponível no core. Assinaturas digitais e conformidade de arquivamento PDF/A exigem uma edição comercial do NextPDF; o adaptador expõe os pontos de entrada, mas o caminho do core não é um produto de assinatura. Consulte /integrations/tcpdf-compat/security-and-operations/ para a declaração precisa.

Para onde ir em seguida

/integrations/tcpdf-compat/install/ — instale o pacote e verifique a conexão com o motor.
/integrations/tcpdf-compat/quickstart/ — crie um primeiro documento executável e respaldado por testes.
/integrations/tcpdf-compat/method-coverage/ — veja exatamente o que cada método do TCPDF faz aqui.
/integrations/tcpdf-compat/migration/ — planeje a estratégia de migração arquivo por arquivo.
/integrations/tcpdf-compat/configuration/ — configure o modo estrito e as definições do adaptador.
/integrations/tcpdf-compat/production-usage/ — execute o adaptador sob carga e em workers.
/integrations/tcpdf-compat/security-and-operations/ — revise a criptografia, a postura em relação a assinaturas e o reforço de segurança.
/integrations/tcpdf-compat/troubleshooting/ — corrija falhas comuns de migração.
/integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ — conecte a facade a uma aplicação e registre os aliases globais de classe.

Veja também

docs/TCPDF_COVERAGE.md — matriz de cobertura autoritativa (no repositório)
Arquivo NOTICE do pacote — declaração de implementação independente