Guias de migração

As receitas e os guias aparecem aqui conforme os repositórios upstream são publicados. Esta página leva você ao conteúdo escrito nos repositórios de origem (nextpdf, nextpdf-Laravel, nextpdf-Symfony e os demais pacotes do ecossistema). Para a documentação disponível hoje, consulte Insider_ (35 artigos, todos os 17 idiomas) ou Escolher uma integração.

Guias de migração

O NextPDF é um motor de Portable Document Format (PDF) 2.0 para PHP. Se você já gera PDFs com outra biblioteca, um guia de migração mapeia a application programming interface (API) dessa biblioteca para o NextPDF e documenta as diferenças de comportamento que você encontrará. Este índice entre repositórios registra de qual biblioteca cada guia parte, qual repositório mantém cada guia e o modelo comum usado por todos eles.

Como é um índice, esta página não faz nenhuma afirmação de comportamento sobre qualquer guia. Cada guia pertence ao seu próprio repositório. O agregador traz o guia para este site e, até que ele chegue, o respectivo link aponta para um placeholder. Toda afirmação de comportamento fica no próprio guia, respaldada por um teste no repositório ou por uma cláusula fixada da ISO 32000-2 / do Cascading Style Sheets Working Group (CSS WG), não aqui.

O modelo único de migração

Todo guia de migração do NextPDF usa o mesmo modelo honesto. Leia cada guia tendo esse modelo em mente:

• Compatível, não idêntico byte a byte. O NextPDF e a biblioteca que você está deixando são implementações independentes. Um documento migrado preserva a intenção funcional, não a identidade em nível de pixel ou de byte. Nenhum guia afirma ser uma substituição direta nem oferecer 100% de compatibilidade.
• A cobertura é uma contagem medida, não uma afirmação. Quando um guia apresenta um número de cobertura, como o número do adaptador do TCPDF, esse número é uma métrica de completude funcional extraída de uma matriz no repositório, no sentido da cláusula 43 da ISO/IEC 25023. É uma contagem medida de métodos cobertos, não uma garantia ampla.
• Cada guia declara abertamente suas diferenças de comportamento. Todo guia inclui uma tabela explícita de diferenças e uma seção “sem suporte / sem equivalente direto”. Uma diferença é uma propriedade documentada do motor, não um defeito.
• Uma mudança de renderizador exige nova revisão. Migrar altera o código e exige uma nova baseline de saída. Cada guia descreve como testar a migração; a aceitação visual é feita por documento e continua sendo responsabilidade do integrador.

Os formatos de migração

Os guias se dividem em dois formatos. Cada formato indica quanto código muda.

• As migrações por reescrita de API não têm camada de compatibilidade: cada ponto de chamada é reescrito com o mapeamento de verbos e o mapa de opções do guia. As migrações de bibliotecas de Hypertext Markup Language (HTML) para PDF (dompdf, mpdf) usam este formato; elas têm como alvo direto o pipeline Html do NextPDF.
• As migrações do tipo substituir-e-depois-migrar fornecem um adaptador quase compatível com a origem, de modo que o primeiro passo é uma troca mínima de dependência. A partir daí, você migra os pontos de chamada para a API moderna de forma incremental e, depois, aposenta o adaptador. A migração do TCPDF usa este formato, por meio do adaptador nextpdf/compat-legacy.

Referência de guia e repositório mantenedor

Todo guia abaixo fica em docs/public/ do repositório mantenedor, e o agregador o traz para este site. O repositório mantenedor é a autoridade sobre as afirmações de comportamento daquele guia; este índice registra apenas o roteamento.

De	Guia	Formato	Repositório mantenedor	Página
Dompdf	Dompdf → pipeline Html do NextPDF	Reescrita de API	nextpdf (core)	Guia do Dompdf dompdf (planejado upstream)
mPDF	mPDF → core do NextPDF	Reescrita de API	nextpdf (core)	Guia do mPDF mpdf (planejado upstream)
TCPDF 6.x	TCPDF → NextPDF por meio do adaptador compat-legacy	Substituir-e-depois-migrar	nextpdf-compat-tcpdf repositório, pacote nextpdf/compat-legacy	Guia do TCPDF tcpdf-compat (planejado upstream)

Os guias dompdf e mpdf ficam no repositório do core porque têm como alvo as APIs do motor central, e os examples/ do core os respaldam. O guia tcpdf-compat fica no repositório compat-tcpdf porque o pacote nextpdf/compat-legacy é responsável pela superfície de comportamento do TCPDF e pelos testes do adaptador que sustentam o guia. Este índice é nativo do repositório de docs porque abrange vários repositórios e não faz nenhuma afirmação de comportamento sobre qualquer guia individual.

Para que serve cada guia

• Dompdf → NextPDF (dompdf (planejado upstream)) — para bases de código que usam o dompdf/dompdf no servidor. Ele mapeia loadHtml/render/output e as chaves de Options para o pipeline Html do NextPDF e delega as expectativas de recursos de CSS à matriz de suporte de CSS apenas-Verificado. Não há camada de compatibilidade da classe Dompdf; você reescreve cada ponto de chamada.
• mPDF → NextPDF (mpdf (planejado upstream)) — para bases de código que usam o mpdf/mpdf. Ele mapeia WriteHTML/Output/AddPage e o array de configuração do construtor para a API do core, com uma diferença no tratamento de fontes: o NextPDF resolve fontes por meio de um único diretório de fontes mais correspondência por CSS e sempre faz subset. Não há camada de compatibilidade da classe Mpdf.
• TCPDF → NextPDF (compat-legacy) (tcpdf-compat (planejado upstream)) — para bases de código TCPDF 6.x que querem a menor mudança inicial. Instale o adaptador, audite sua superfície real em modo estrito contra a matriz de cobertura do repositório, migre os pontos de chamada para fora do adaptador e, então, adicione por cima a estrutura marcada PDF/Universal Accessibility (PDF/UA-2), um recurso que o TCPDF nunca teve. O adaptador é um andaime, não o destino, e não é uma garantia de substituição direta.

Como os links dos guias são resolvidos

Cada placeholder [[…]] acima aponta para uma página que fica no repositório mantenedor, em docs/public/migration/, e o agregador puxa essa página para este site. Os slugs de destino seguem uma convenção:

/migration/<source>/

O token <source> é o nome curto da biblioteca da qual você está migrando: um entre dompdf, mpdf ou tcpdf-compat, conforme listado na tabela de referência de guias acima. Até que uma página de destino seja agregada, o link correspondente continua sendo um placeholder e não resolve. Este índice não faz nenhuma afirmação de comportamento sobre qualquer guia de destino; ele registra apenas o roteamento e o modelo comum de migração.

Veja também

• Matriz de suporte de CSS — a autoridade apenas-Verificado para as expectativas de recursos de CSS nos guias dompdf e mpdf.
• Livro de receitas de integração — o índice entre repositórios dos pacotes de integração do ecossistema. Ele trata de outra preocupação: conectar o motor, não migrar para ele.