Migrando de bibliotecas legadas: TCPDF, FPDF e cia.

SpecSpec: ISO 32000-2ISO 32000-2SpecSpec: ISO 19005-4ISO 19005-4SpecSpec: ETSI EN 319 142-1ETSI EN 319 142-1

Visão geral

Se os seus PDFs são gerados por TCPDF, FPDF, mPDF ou dompdf, o código provavelmente ainda funciona. É justamente por isso que o problema passa fácil despercebido. A biblioteca roda, o arquivo abre, e a lacuna só aparece no dia em que alguém pede um documento assinado, arquivável ou acessível e a resposta é “daqui a gente não consegue”.

Esta página é a história da migração: quais são esses muros, por que eles são estruturais e não acidentais, e como o NextPDF lhe dá um caminho em etapas para sair deles — incluindo uma superfície de compatibilidade com TCPDF que é um auxílio de migração, não a promessa de um substituto byte a byte que entra no lugar.

Por que isso importa

Uma biblioteca de PDF não é uma chamada de renderização que você faz uma vez. É uma dependência que seus documentos herdam por todo o tempo em que existirem. Quando essa dependência para de evoluir, seus documentos deixam de conseguir fazer coisas novas — e você descobre isso no pior momento possível, quando um cliente, um auditor ou um regulador define o patamar.

Os muros têm esta cara. O formato seguiu em frente: o PDF 2.0 é a edição atual do padrão (SpecSpec: ISO 32000-2ISO 32000-2), e um escritor preso à estrutura 1.x está atrás do formato que o restante do seu toolchain pressupõe. A assinatura é rasa ou aparafusada por cima, bem aquém dos perfis baseline do PAdES que fazem uma assinatura se sustentar (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4). A saída de arquivamento para a família PDF/A, e a estrutura marcada para acessibilidade, ou estão ausentes ou são frágeis. E a própria API não tem tipagem — orientações como string, booleanos posicionais, padrões que você descobre por acidente — então o compilador não pode lhe ajudar e um revisor também não.

Nenhum desses pontos é um bug que você consiga remendar. Eles são o formato de uma ferramenta construída para uma década anterior, e várias dessas ferramentas já não avançam ativamente rumo aos padrões que seus documentos agora precisam atender.

A versão resumida

• As bibliotecas PHP de PDF legadas, na maioria, ainda rodam. O problema é o que elas comumente não conseguem produzir com plena conformidade moderna: PDF 2.0, assinaturas compatíveis com o baseline, PDF/A validado, acessibilidade marcada — o suporte nas bibliotecas citadas é limitado ou ausente.
• O NextPDF é um motor em PHP 8.4 que escreve PDF 2.0 por padrão, com tipos estritos, perfis de arquivamento e assinatura PAdES como saídas de primeira classe.
• Você não precisa reescrever tudo no primeiro dia. A superfície de compatibilidade com TCPDF permite que chamadas familiares continuem funcionando enquanto você migra a lógica de documento que importa.
• Essa superfície é compatível com, não byte a byte idêntica a TCPDF. É uma ponte ao longo da migração, com diferenças de comportamento documentadas — não a afirmação de que todo script roda sem alterações.
• O teste honesto é se as novas capacidades valem a mudança. Para algumas cargas de trabalho não valem, e nós dizemos isso com todas as letras.

Como o NextPDF aborda isso

A abordagem é fazer da migração uma sequência, não um salto. Você continua produzindo documentos o tempo todo, e troca as restrições antigas uma de cada vez em vez de apostar um release em uma reescrita de uma só tacada.

1. InventárioCatalogue o que seus documentos realmente precisam emitir — assinaturas, perfis de arquivamento, estrutura marcada, fontes — não apenas quais chamadas você faz hoje.
2. PonteAdote a superfície de compatibilidade com TCPDF para que os pontos de chamada existentes continuem produzindo arquivos enquanto o motor por baixo passa a ser o NextPDF.
3. PorteMova a lógica de documento que importa para a API nativa tipada, onde a intenção é explícita e o compilador a verifica.
4. AtualizeAtive as saídas que muitas bibliotecas legadas não alcançam com plena conformidade moderna: estrutura PDF 2.0, PDF/A validado, assinaturas PAdES, acessibilidade marcada.
5. VerifiqueConfirme o resultado contra um validador real, para que 'arquivável' ou 'assinado' signifique que uma ferramenta concorda, não apenas que o arquivo abriu.

A staged migration off a legacy PDF library: start on the compatibility surface so existing calls keep working, then move document logic onto the typed native API, then turn on the standards-grade outputs (PDF 2.0, PDF/A, PAdES, accessibility) that many legacy libraries cannot produce with full modern conformance.

O PDF 2.0 é a base, não uma flag de recurso. O NextPDF escreve a edição atual do formato por padrão (SpecSpec: ISO 32000-2ISO 32000-2), e pode serializar estruturas mais antigas quando um perfil as pede. Uma biblioteca congelada na estrutura 1.x não consegue lhe encontrar aqui; não é uma configuração que está faltando, é uma era que ela antecede.

Arquivamento e acessibilidade são propriedades do escritor. Produzir um arquivo que um validador aceita como PDF/A é algo que o motor tem de fazer enquanto escreve — não pode ser grampeado depois (SpecSpec: ISO 19005-4ISO 19005-4). O mesmo vale para a estrutura marcada que torna um PDF acessível. O NextPDF constrói isso durante a geração, que é exatamente o passo que muitas ferramentas legadas não conseguem dar — ou dão apenas parcialmente, aquém do que um validador aceita.

A assinatura passa do patamar baseline. As assinaturas eletrônicas avançadas em um PDF seguem os perfis PAdES (SpecSpec: ETSI EN 319 142-1, §4ETSI EN 319 142-1 §4), onde o resumo cobre uma faixa de bytes declarada e a assinatura carrega os metadados que um validador verifica. Um auxiliar de assinatura aparafusado raramente atinge esse patamar. O NextPDF o trata como uma saída de primeira classe, não como algo de última hora.

A superfície de compatibilidade é a ponte, declarada com honestidade. A camada de compat com TCPDF existe para que seus pontos de chamada existentes continuem produzindo documentos enquanto você migra as partes que importam. Ela segue o mesmo modelo de todo guia de migração do NextPDF: compatível com a biblioteca de origem, não byte a byte idêntica, com as diferenças de comportamento registradas por escrito. Essa honestidade é o ponto — uma afirmação silenciosa de “99% drop-in” é justamente o tipo de palpite que este motor é construído para recusar.

Human-factors note:Human-factors note

O motivo para migrar raramente é o código que você tem hoje; é o documento que lhe pedirão amanhã. Manutenibilidade é uma propriedade de qualidade nomeada — o quão prontamente um sistema pode ser analisado e modificado conforme as necessidades mudam (SpecSpec: ISO/IEC 25010, §3.6ISO/IEC 25010 §3.6). Uma dependência que parou de evoluir a corrói em silêncio, e você só sente o custo quando um novo requisito chega e a resposta tem de ser “daqui não”. Uma mudança em etapas paga esse custo no seu cronograma, enquanto os documentos seguem fluindo, em vez de tudo de uma vez sob prazo.

Exemplo prático

O formato de uma migração é pequeno no ponto de chamada. O código antigo continua produzindo um arquivo pela superfície de compatibilidade; o código novo declara a intenção pela API nativa tipada e pede uma saída que a biblioteca legada não alcança, ou alcança apenas com conformidade limitada.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

O primeiro bloco é o ponto de apoio: nada na sua aplicação precisa mudar para que os documentos continuem fluindo. O segundo é o destino: uma chamada tipada onde “retrato”, “saída em string” e a fonte são explícitos, e onde arquivamento, assinatura e acessibilidade passam a ser saídas que você pode ligar em vez de muros nos quais você esbarra.

Equívoco comum

A esperança frequente é “deve existir uma flag que faz minha biblioteca antiga produzir PDF 2.0 e assinaturas”. Não existe. Essas não são opções que uma biblioteca madura esqueceu de expor; são capacidades em torno das quais a arquitetura dela nunca foi construída. Você não consegue configurar o caminho até uma edição de formato ou um perfil de assinatura que um escritor não implementa.

O equívoco espelhado é achar que o NextPDF é um substituto 100% drop-in do TCPDF, de modo que a migração seria de graça. Não é, e não vamos fingir o contrário. A superfície de compatibilidade cobre uma fatia real e documentada da API para lhe levar através da mudança; algumas chamadas se comportam de forma diferente, e poucas estão fora do escopo. Trate-a como uma ponte com um mapa publicado, não como uma garantia de que todo script legado roda intocado.

Limites e fronteiras

TCPDF-compatibility surface as a migration aid — edition availability

Edition	Availability
Core	○ A superfície de compatibilidade é compatível com, não byte a byte idêntica a TCPDF. Ela cobre um subconjunto documentado da API para manter os pontos de chamada existentes produzindo arquivos durante a migração. É uma ponte, não um drop-in: alguns comportamentos diferem e algumas chamadas não são suportadas, tudo listado nas páginas de cobertura de métodos e de migração. O destino é a API nativa tipada, onde vive a saída de nível de padrões.
Pro	●Available
Enterprise	●Available

A migração é um meio, não uma virtude. Se seus documentos são simples, sua biblioteca ainda é mantida, e você nunca vai precisar de PDF 2.0, assinatura, PDF/A ou acessibilidade, a resposta honesta pode ser ficar onde está — o custo da troca é real e uma mudança de que você não precisa é uma mudança que você não deveria fazer. A página sobre quando não usar o NextPDF traça essa linha sem hesitar.

Esta página descreve o caminho da migração e os alvos do motor. A cobertura exata da API, as diferenças de comportamento e o procedimento passo a passo vivem na documentação de compatibilidade, que é a autoridade sobre o que cada chamada faz. Nada aqui promete que um script legado arbitrário roda sem alterações.

Documentos relacionados

• O que o PDF 2.0 mudou — a edição de formato que muitas bibliotecas legadas não conseguem emitir, e por que isso importa.
• A superfície de compatibilidade com TCPDF — o guia autoritativo sobre o que a ponte cobre e onde ela difere.
• Quando não usar o NextPDF — a fronteira honesta, para que uma migração de que você não precisa seja uma que você pode pular.
• Um motor, todos os frameworks — onde o motor para o qual você migra se encaixa na stack que você já roda.

Glossário

• PDF 2.0 — a edição atual do padrão Portable Document Format (ISO 32000-2). Expandido no primeiro uso; o formato que o NextPDF escreve por padrão.
• PDF/A — a família de conformidade de arquivamento (a série ISO 19005) que define o que torna um PDF seguro para preservar a longo prazo. Uma propriedade que o escritor precisa produzir, não uma que um chamador possa adicionar depois.
• PAdES — PDF Advanced Electronic Signatures, a família de perfis da ETSI (EN 319 142) para embutir assinaturas de nível de padrões em um PDF. Expandido no primeiro uso; coberto em profundidade nas páginas sobre assinatura.
• Superfície de compatibilidade — uma camada de API com o formato de uma biblioteca de origem (aqui, TCPDF) que permite que os pontos de chamada existentes continuem funcionando durante a migração. Compatível com, não byte a byte idêntica à original — uma ponte, não um drop-in.
• Substituto drop-in — um substituto que roda o código existente sem alterações. A superfície de compat com TCPDF é deliberadamente não descrita assim; é um auxílio de migração documentado, com diferenças de comportamento conhecidas.