Cobertura de métodos do TCPDF no compat-legacy do NextPDF

Visão geral

nextpdf/compat-legacy é uma camada de compatibilidade, não um fork do TCPDF nem um clone comportamental garantido. Ele expõe os nomes de métodos públicos, a ordem de parâmetros e os valores padrão do TCPDF 6.x sobre o motor central do NextPDF. A maioria das chamadas mapeia diretamente para uma operação de Document do NextPDF. Um conjunto pequeno e definido aceita parâmetros legados que o NextPDF não respeita ou que não têm efeito.

Esta página resume a auditoria por método. A matriz de cobertura autoritativa, verificada por testes, fica no repositório em docs/TCPDF_COVERAGE.md. Se esta página e a matriz no repositório divergirem, a matriz no repositório prevalece, porque a suíte de testes a verifica.

Use esta página para responder a uma pergunta antes de migrar: para cada método do TCPDF que a base de código chama, o que o adaptador faz de fato?

Resumo da cobertura

A auditoria examinou cerca de 120 métodos públicos do TCPDF 6.x. Cada método foi colocado em exatamente uma de quatro categorias.

Categoria	Contagem	O que isso significa para você
Espelhado — totalmente delegado	94	A chamada mapeia diretamente para um método de `Document` do NextPDF. O comportamento é compatível para os parâmetros documentados.
Ignorar-em-silêncio — parcial	15	O método é executado e produz saída, mas um ou mais parâmetros do TCPDF não têm efeito. Essa diferença de comportamento é documentada.
Não implementado — corpo no-op	4	O método existe para compatibilidade de código-fonte, mas não faz nada.
Não aplicável	7	O método do TCPDF não tem efeito na saída PDF; excluído intencionalmente.
Métodos de drift da API moderna adicionados	17	Métodos de Document do NextPDF v5.1+ expostos no adaptador para que o código de API mista compile. Eles não têm equivalente no TCPDF 6.x.

Esses números vêm de docs/TCPDF_COVERAGE.md §Summary. A suíte de testes verifica a matriz por meio de tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php e tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php.

Nota de redação. Este pacote não afirma ser um “substituto direto (drop-in replacement)” nem “100% compatível com o TCPDF”. Ele cobre 94 dos cerca de ~120 métodos do TCPDF examinados por delegação direta. Os métodos restantes têm diferenças de comportamento documentadas, descritas abaixo. A formulação precisa é alternativa compatível com o TCPDF com uma superfície de compatibilidade conhecida e testada.

Uma observação sobre as contagens de métodos

O adaptador é construído a partir de 25 traits de responsabilidade única (src/Compat/Tcpdf/Concerns/) que expõem 273 métodos públicos no total, além de um pequeno número de métodos de ciclo de vida e de escape na própria classe TCPDF. As categorias de cobertura acima contam métodos distintos da superfície de API do TCPDF 6.x (~120), não a contagem total de métodos públicos do adaptador. Os dois números medem coisas diferentes: cobertura da superfície de API e tamanho da implementação. Se o README.md do pacote citar uma contagem menor de traits ou de métodos, trate docs/TCPDF_COVERAGE.md e esta página como fontes autoritativas. O resumo do README é anterior ao trait AdaptsDriftV51.

1. Métodos espelhados — delegação compatível

Noventa e quatro métodos mapeiam diretamente para a instância subjacente de NextPDF\Core\Document. Os nomes PascalCase do TCPDF mapeiam para nomes camelCase do NextPDF quando o motor usa camelCase. O adaptador aceita as duas grafias para compatibilidade futura e retroativa.

Grupos representativos (tabela completa: docs/TCPDF_COVERAGE.md §1):

Área do TCPDF	Métodos de exemplo	Trait do adaptador
Ciclo de vida	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
Páginas	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
Texto	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
Fontes	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
Cores	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
Desenho	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
Transformações	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
Navegação	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

Para esses métodos, o comportamento observado é compatível com o TCPDF 6.x para os parâmetros documentados pelo NextPDF. O adaptador não garante saída PDF idêntica byte a byte. O motor subjacente é uma implementação independente de PDF 2.0, então os bytes podem diferir mesmo quando o resultado visível é equivalente. Se os testes verificarem os bytes exatos do PDF em vez do conteúdo renderizado, espere precisar refazer a baseline dessas verificações. Consulte /integrations/tcpdf-compat/migration/ para a estratégia recomendada de refazer a baseline.

2. Métodos de ignorar-em-silêncio — diferenças de comportamento documentadas

Esses 15 métodos são executados e produzem saída, mas pelo menos um parâmetro do TCPDF é aceito por compatibilidade de código-fonte e depois ignorado. Leia esta seção antes de migrar. Essas chamadas não falham; elas fazem menos do que o original do TCPDF, silenciosamente.

Método do TCPDF	Parâmetros ignorados	Alternativa compatível
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	O `image()` do NextPDF recebe file, x, y, width, height. Para uma imagem clicável, desenhe a imagem e depois adicione `Document::link()` sobre o mesmo retângulo. Mascaramento de imagem e imagens alternativas não são suportados.
`writeHTML()`	ln, fill, reseth, cell, align	O `writeHtml()` do NextPDF trata apenas do conteúdo. Envolva o HTML em um bloco posicionado por meio da API moderna para controlar o layout.
`writeHTMLCell()`	border (forma de string), ln, fill, reseth, autopadding	Largura, altura, posição e uma borda booleana são respeitadas; um layout de célula mais rico não tem mapeamento.
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Apenas posição e tamanho.
`ImageSVG()`	link, align, palign, border, fitonpage	Apenas posição e tamanho.
`SetProtection()`	mode (diferente de zero), pubkeys (não vazio)	O NextPDF sempre usa AES-256 para o handler padrão. Para criptografia baseada em certificado, use o moderno `setPublicKeyEncryption()` exposto no adaptador (consulte /integrations/tcpdf-compat/security-and-operations/).
`Bookmark()`	style, color, x, isNamedDest	Título, nível e posição y são respeitados.
`setDestination()`	page, x	Nome e posição y são respeitados.
`Link()`	spaces	Rastreamento interno de espaços em branco do TCPDF; sem equivalente no motor.
`Annotation()`	chaves de opção além de Subtype, spaces	Tipo, posição e texto são preservados.
`SetLineStyle()`	detalhes do padrão de tracejado além da largura	As propriedades centrais de linha são mapeadas.
`setAlpha()`	mapeamento parcial de modos de mesclagem	Alguns nomes de modos de mesclagem não têm equivalente no motor.
`Polycurve()`	lista completa de parâmetros	No-op no modo padrão; sem equivalente no motor.
`PieSectorXY()`	lista completa de parâmetros	Mapeamento parcial (as linhas do centro à borda diferem).
`RoundedRectXY()`	raio por canto	Apenas raio de canto uniforme.

A forma como o adaptador expõe essas diferenças depende do modo estrito (consulte /integrations/tcpdf-compat/configuration/). Com o modo estrito desligado, o padrão retrocompatível, essas chamadas degradam silenciosamente. Com o modo estrito ligado, qualquer chamada que ignore um parâmetro lança TcpdfNotImplementedException com a lista exata de parâmetros ignorados e uma dica de migração. O modo estrito é uma ferramenta de auditoria, não uma configuração de produção.

O design do modo estrito segue o princípio de que quem faz a chamada precisa ser capaz de perceber quando sua intenção não foi respeitada. O OWASP ASVS 5.0 §16.5.3 afirma que as aplicações devem falhar de forma controlada e segura e evitar condições de fail-open. A perda silenciosa de parâmetros é uma falha de experiência do desenvolvedor, e não uma vulnerabilidade, mas o mesmo princípio de falhar de forma explícita se aplica. O digest fixado da cláusula está no citations do front-matter da página.

3. Métodos não implementados — corpos no-op

Quatro métodos existem para que o código-fonte legado compile, mas seus corpos não fazem nada. Com o modo estrito ligado, três lançam TcpdfNotImplementedException. O quarto (Open()) é um no-op seguro deliberado que nunca lança, porque você sempre pode removê-lo do código legado com segurança.

Método do TCPDF	Comportamento	Substituição
`setSignature()`	No-op (não armazena nada utilizável). Lança no modo estrito.	A assinatura digital exige uma edição comercial do NextPDF. Use a API moderna de assinatura com um objeto de valor `CertificateInfo`; consulte /integrations/tcpdf-compat/security-and-operations/.
`addEmptySignatureAppearance()`	No-op. Lança no modo estrito.	Mesma restrição de edição comercial que `setSignature()`.
`endPage()`	No-op. Lança no modo estrito.	O NextPDF gerencia o ciclo de vida das páginas automaticamente. Remova a chamada.
`Open()`	No-op seguro. Nunca lança.	O NextPDF abre o documento automaticamente. Remover a chamada é sempre seguro.

A assinatura não está disponível no motor central por meio deste adaptador. O adaptador expõe um ponto de entrada moderno para assinatura que delega ao motor. O suporte básico de assinatura é restrito a uma edição comercial. Esta documentação não faz nenhuma afirmação sobre perfis de assinatura de validação de longo prazo ou com carimbo de tempo para qualquer edição. Consulte /integrations/tcpdf-compat/security-and-operations/ para a declaração exata e conservadora.

4. Métodos não aplicáveis

Sete métodos do TCPDF não têm efeito na saída PDF e são excluídos intencionalmente. Você pode chamá-los com segurança.

Método do TCPDF	Por que foi excluído
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	O estado é mantido no adaptador, mas não é conectado aos metadados XMP do documento. Não visível na saída.
`setSRGBmode()`	O gerenciamento de cores do NextPDF é independente desta flag.
`setPDFVersion()`	O NextPDF seleciona a versão do PDF a partir do seu perfil de conformance/output; não há setter direto. O adaptador emite um aviso e continua.
`setDocInfoUnicode()`	O NextPDF é sempre Unicode; a flag é um no-op por design.
`setDefaultMonospacedFont()`	Sem equivalente no motor; em vez disso, aplica-se a estilização por HTML/CSS.
`setFontSubsetting()`	O NextPDF sempre faz subsetting das fontes incorporadas; a flag está efetivamente sempre ligada.

A versão do PDF é fixada pelo motor. A saída é escrita como PDF 2.0 (ISO 32000-2). A ISO 32000-2 §7.5.2 especifica que um escritor conforme identifica a versão do documento — no cabeçalho do arquivo ou na entrada Version do catálogo — como 2.0. Ela também especifica que salvar um arquivo não rebaixa a versão do arquivo. Isso corresponde ao comportamento do adaptador: chamadas como setPDFVersion('1.4') não podem rebaixar a saída para uma versão de PDF mais antiga por meio deste adaptador. O digest fixado da cláusula está no citations do front-matter da página.

5. Métodos de drift da API moderna

Dezessete métodos do core do NextPDF v5.1+ são expostos no adaptador (trait AdaptsDriftV51) para que o código que mistura a API do TCPDF com a API moderna continue compilando. Eles não têm equivalente no TCPDF 6.x. Exemplos: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Trate-os como API moderna, não como parte do contrato de compatibilidade com o TCPDF.

6. Orientações de descontinuação e substituição

Se o código chama…	Status	Faça isto em vez disso
`Error()`	Comportamento alterado (reforçado)	O adaptador substitui o `die()` do TCPDF por uma `RuntimeException` lançada. Envolva chamadas de risco em `try`/`catch`; não dependa do encerramento do processo.
`setPDFVersion()`	Não aplicável	Remova. A saída é sempre PDF 2.0.
`setUserRights()`	Descontinuado no PDF 2.0	Remova. A chamada emite um aviso `E_USER_DEPRECATED` e é ignorada.
`setSignature()`	Não implementado no core	Migre para a API moderna de assinatura em uma edição comercial.
`Image(...)` com parâmetros extras	Ignorar-em-silêncio	Reduza para file, x, y, w, h; adicione `Document::link()` para imagens clicáveis.
`endPage()` / `Open()`	Não implementado / no-op	Remova.

7. Passos para uma migração segura

Instale o pacote e execute a suíte existente contra o adaptador sem alterações de código. Consulte /integrations/tcpdf-compat/install/ e /integrations/tcpdf-compat/quickstart/.
Habilite o modo estrito em uma execução de auditoria dedicada (não em produção): $pdf->setStrictMode(true);. Colete cada TcpdfNotImplementedException. Cada uma identifica exatamente os parâmetros ignorados e inclui uma dica de migração.
Para cada ponto de chamada, decida se vai descartar o parâmetro ignorado ou migrar aquela chamada para a API moderna por meio de $pdf->getDocument().
Refaça a baseline de qualquer teste que verifique os bytes exatos do PDF; em vez disso, verifique o conteúdo renderizado ou propriedades estruturais.
Desligue o modo estrito e implante o caminho de código auditado. Mantenha um job de CI periódico em modo estrito para detectar regressões conforme você refatora.

Procedimento completo com código: /integrations/tcpdf-compat/migration/.

Veja também

docs/TCPDF_COVERAGE.md — matriz de cobertura autoritativa, verificada por testes (no repositório)
/integrations/tcpdf-compat/migration/ — estratégia de migração de ponta a ponta do TCPDF para o NextPDF
/integrations/tcpdf-compat/configuration/ — modo estrito e configuração do adaptador
/integrations/tcpdf-compat/security-and-operations/ — postura de criptografia e assinatura
/integrations/tcpdf-compat/integration/ — integração do adaptador em uma aplicação
/integrations/tcpdf-compat/boot-and-discovery/ — registro de alias de classe e exposição de facade