Migração do mPDF para o NextPDF

Visão geral

Este guia ajuda você a migrar uma base de código baseada em mPDF para o núcleo do NextPDF. No mPDF, a principal chamada de conteúdo é WriteHTML(), que mapeia diretamente para Document::writeHtml(). A maior parte do trabalho está no mapeamento do array de configuração do construtor (o mPDF configura tudo por meio de um único array associativo passado para new Mpdf([...])) e nas diferenças no tratamento de fontes. NextPDF e mPDF são mecanismos independentes, portanto um documento migrado é compatível com a saída do mPDF, mas não idêntico byte a byte a ela. Este guia cobre o mapa de verbos, o mapa do array de configuração, a diferença de fontes, a diferença de suporte a Cascading Style Sheets (CSS), as diferenças de comportamento e uma sequência segura.

A matriz de suporte a Cascading Style Sheets (CSS) define quais recursos de Hypertext Markup Language (HTML) e CSS são Verificados. Este guia descreve o comportamento; ele não declara equivalência visual com o mPDF.

Instalação

composer require nextpdf/core:^3

Mantenha mpdf/mpdf instalado enquanto você faz a migração. Remova-o após a transição final (consulte sequência de migração segura).

Visão conceitual

O objeto Mpdf do mPDF combina configuração e renderização por trás de uma única interface. Um array de construtor faz a configuração, e WriteHTML() mais os verbos de paginação (AddPage, SetHTMLHeader, SetHTMLFooter) controlam o resultado. NextPDF separa a configuração no objeto de valor imutável NextPDF\Core\Config e escreve conteúdo com Document::writeHtml(). Não há uma string de “modo” no construtor. NextPDF analisa o HTML que você passa e, em seguida, emite o documento com save(), output() ou getPdfData().

Fontes: o mPDF vem com um diretório de fontes, um mapa fontdata e um conjunto de fallback de “fontes principais”. NextPDF resolve as fontes a partir de um único diretório de fontes mais a correspondência de font-family do CSS, e sempre subdivide (subset) as fontes incorporadas (International Organization for Standardization (ISO) 32000-2 §9, iso32000_2_sec9#x1.x45.p7). A correspondência e o fallback de fontes são específicos do mecanismo (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13), portanto a substituição de glifos pode diferir. Essa é a principal diferença visível, abordada na diferença no tratamento de fontes.

Superfície da API

A API de HTML do NextPDF está documentada na referência do módulo Html. Os principais pontos de entrada são Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string e o objeto de valor NextPDF\Core\Config.

Mapeamento de verbos da API

Os nomes dos métodos públicos do mPDF abaixo foram confirmados no repositório público upstream (mpdf/mpdf, development); consulte o sidecar de proveniência _source-sidecar-upstream-api.md no repositório. Nenhum texto da documentação upstream é reproduzido.

mPDF	NextPDF	Notas
`new Mpdf([...])`	`Document::createStandalone($config)`	O array de configuração do mPDF mapeia para `NextPDF\Core\Config`; consulte mapa de configuração. Use `DocumentFactory` para workers de longa duração.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	Mapeamento direto. O segundo argumento `$mode` do mPDF (documento completo vs. apenas CSS vs. elemento) não tem análogo no NextPDF; passe HTML completo.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	Região de HTML posicionada e dimensionada; mapeie os argumentos x/y/largura/altura.
`$mpdf->AddPage(...)`	`$doc->addPage()`	NextPDF não aceita como argumentos as substituições de orientation/format/margem por chamada do mPDF; em vez disso, altere o modelo do documento entre chamadas.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	header/footer por meio da API de Layout	Os cabeçalhos HTML recorrentes do mPDF mapeiam para o mecanismo de header/footer do NextPDF, não para HTML inserido no início do corpo.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	Os caracteres de destino do mPDF (`I`/`D`/`F`/`S`) mapeiam para o enum `OutputDestination` (`Inline`/`Download`/file via `save()`/string via `getPdfData()`).
`$mpdf->Output('','S')`	`$doc->getPdfData()`	Retorna bytes.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	Escreve em um caminho de arquivo.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	Cai no dicionário de informações §14 / Extensible Metadata Platform (XMP) da ISO 32000-2 (`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (API de segurança)	As permissões dependem da cooperação do leitor, não são controle de acesso — consulte Notas de segurança.

Exemplo de código — Início rápido

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

// mPDF:
//   $mpdf = new \Mpdf\Mpdf();
//   $mpdf->WriteHTML('<h1>Invoice</h1>');
//   $mpdf->Output('out.pdf', \Mpdf\Output\Destination::FILE);

// NextPDF — default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->writeHtml('<h1>Invoice</h1>');
$doc->save(__DIR__ . '/out.pdf');

echo "Wrote out.pdf\n";

Exemplo de código — Produção

Este exemplo está alinhado com examples/04-text-and-fonts.php, a referência executável para os conceitos de tratamento de fontes deste guia. Ele usa um tamanho de página explícito, margens e um corpo de conteúdo que exercita a seleção de fontes.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// Equivalent of: new Mpdf(['format'=>'A4','margin_left'=>20, ...]).
// Margin constructor order is (top, right, bottom, left) — NOT L,R,T,B.
$config = new Config(
    pageSize: new PageSize(595.276, 841.890, 'A4'),
    margins: new Margin(16.0, 20.0, 16.0, 20.0), // top,right,bottom,left in points
    fontsDirectory: __DIR__ . '/fonts',
);

$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->addPage();

$html = <<<'HTML'
<h1 style="font-family:'DejaVu Sans';color:#1E3A8A;">Quarterly Report</h1>
<p>Body text resolves through CSS font-family matching against the configured
fonts directory. mPDF's fontdata map has no direct analogue — register the
family via CSS and the fonts directory instead.</p>
HTML;

$doc->writeHtml($html);

// Equivalent of $mpdf->Output('report.pdf', Destination::DOWNLOAD):
$doc->output('report.pdf', OutputDestination::Download);

Casos extremos e armadilhas

Argumento $mode em WriteHTML. WriteHTML($html, $mode) do mPDF (2 = apenas CSS, 1 = elemento) não tem equivalente. Coloque o CSS no HTML que você passa; não existe uma sequência de “escrever o CSS e depois escrever o corpo”.
Substituições por AddPage. O mPDF permite que AddPage() altere format/orientation no meio do documento por meio de argumentos. NextPDF addPage() não aceita esses argumentos; as mudanças de tamanho são modeladas ao longo do documento, não na chamada da página.
HTML de cabeçalho/rodapé. O mPDF registra cabeçalhos recorrentes como fragmentos HTML separados; não os cole no corpo. Mapeie-os para o mecanismo de header/footer do NextPDF.
Nomes de fontes. O mPDF normaliza os nomes de fontes por meio de sua tabela fontdata/core-font. NextPDF faz a correspondência da font-family do CSS com o diretório de fontes; um alias do mPDF que resolvia silenciosamente pode precisar de um @font-face/family explícito.
Caracteres de destino. 'I'/'D'/'F'/'S' não são aceitos; use o enum OutputDestination ou save()/getPdfData().

Desempenho

writeHtml() é de passagem única (ADR-001); o pico de memória acompanha o tamanho do documento, não um Document Object Model (DOM) retido. Orçamento para o exemplo deste guia: wall_ms: 2000, peak_mb: 128. Para documentos longos, divida o conteúdo entre chamadas addPage() em vez de passar uma única string gigante. Essa é a mesma orientação que se aplica à divisão em blocos via $mode do mPDF, expressa por meio do modelo de páginas.

Notas de segurança

As permissões dependem da cooperação do leitor. SetProtection() → setEncryption() fornece confidencialidade, não controle de acesso: os bits de permissão da ISO dependem de um leitor cooperante. Não apresente criptografia como controle de acesso aos usuários.
Metadados. SetTitle() e as informações do documento caem no dicionário de informações §14 / XMP da ISO 32000-2 (iso32000_2_sec14#x1.x5.p5); nunca armazene segredos ali.
NextPDF não executa scripts internos do documento; nenhuma diretiva do mPDF altera isso aqui.

Conformidade

Declaração	Especificação	Cláusula
As fontes são escritas como programas de fonte embedded/subset.	ISO 32000-2	§9
format/margins da página mapeiam para a caixa delimitadora da página.	ISO 32000-2	§7
Os metadados de título / proteção caem no dicionário de informações / XMP.	ISO 32000-2	§14
A correspondência / fallback de fontes é específica do mecanismo.	CSS Fonts 4	§5.5

NextPDF produz conteúdo ISO 32000-2; ele não declara identidade visual com o mPDF. Reavalie a saída sempre que você trocar de renderizador.

Contexto comercial

Não se aplica. O núcleo do NextPDF cobre o caminho de migração do mPDF descrito aqui.

Veja também

Detalhe de migração (seções obrigatórias R6)

Para quem é isto

Equipes que executam mpdf/mpdf para HTML-para-PDF no lado do servidor. Se o seu código foi construído em torno de new Mpdf([...]) + WriteHTML + Output (+ header/footer opcional), o mapeamento de verbos e o mapa de configuração cobrem esse caso.

Escopo

No escopo: o array de configuração do construtor Mpdf, WriteHTML/Output/AddPage, headers/footers, fontes, proteção, metadados. Fora do escopo: as classes internas do mPDF e a superfície auxiliar de Quick Response (QR)/barcode/watermark. Mapeie esses recursos para os módulos correspondentes do NextPDF — Barcode, Graphics — que não são abordados aqui.

Mapa de compatibilidade

Compatibilidade comportamental, não um shim drop-in: NextPDF não fornece um shim de classe Mpdf. Reescreva cada local de chamada. Use as linhas Verificadas da matriz de suporte a CSS para definir as expectativas sobre recursos CSS.

Mapa do array de configuração do construtor

As chaves de configuração do mPDF abaixo foram confirmadas no repositório público upstream (mpdf/mpdf, development). Nenhum texto da documentação upstream é reproduzido.

chave de configuração do mPDF	NextPDF	Notas
`mode`	(sem equivalente)	A string de modo do mPDF (`'utf-8'`, `'c'`, `'+aCJK'`, …) seleciona o comportamento de font/script. NextPDF é sempre Unicode; texto em chinês, japonês e coreano (CJK) é tratado pela seleção de fontes, não por um modo. Descarte a chave.
`format`	`Config->pageSize` (objeto de valor (VO) `PageSize`)	Os formatos nomeados tornam-se dimensões explícitas em pontos; arrays `[w,h]` mapeiam para um `PageSize`.
`orientation`	troque o `PageSize` width/height	Sem flag de orientação; paisagem significa largura > altura.
`default_font_size`	font-size base do CSS	Defina isto na sua folha de estilo base, não em uma chave do construtor.
`default_font`	CSS `font-family` / fonte registrada	Defina a família padrão por meio de CSS / registro de fontes.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (VO `Margin`) em pontos	Use um único objeto de valor `Margin`; a ordem do construtor é `Margin(top, right, bottom, left)` (verifique em `src/ValueObjects/Margin.php`), e não a ordem das chaves do mPDF.
`margin_header` / `margin_footer`	deslocamento de header/footer por meio da API de Layout	Mapeie esses valores para a configuração de header/footer do NextPDF, não para chaves do construtor.

Diferença no tratamento de fontes

Diretório de fontes único. A lista de diretórios de fontes do mPDF, o mapa fontdata e o fallback de fontes principais convergem para Config->fontsDirectory mais a correspondência de font-family do CSS.
Sempre subdivide (subset). NextPDF sempre subdivide as fontes incorporadas (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); as flags de subset do mPDF não têm equivalente e não são necessárias.
A correspondência é específica do mecanismo. A correspondência e o fallback de fontes diferem por mecanismo (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); um alias de fonte do mPDF pode precisar de um @font-face explícito ou do nome exato da família. Refaça a baseline da renderização de glifos após a migração. Diferenças de substituição são esperadas, não são defeitos.

Diferenças de comportamento

Substituição de fontes (veja acima) — a principal diferença visível.
Sem $mode em WriteHTML — passe HTML completo com CSS embutido.
Sem substituição de formato por AddPage — as mudanças de tamanho são modeladas ao longo do documento.
As permissões dependem da cooperação do leitor (consulte Notas de segurança).
Mecanismo de layout independente — a quebra de linha / paginação difere em conteúdo denso; refaça a baseline das comparações visuais.

Essas são diferenças de comportamento documentadas, não defeitos em nenhum dos mecanismos.

Sem suporte / sem equivalente direto

mode — string de construtor não modelada (sempre Unicode).
Argumentos de format/orientation/margem por AddPage() — não são argumentos no NextPDF.
mapa fontdata do mPDF — substituído pelo diretório de fontes + correspondência de CSS.
caracteres de destino 'I'/'D'/'F'/'S' do mPDF — substituídos pelo enum OutputDestination + save()/getPdfData().

Sequência de migração segura

Adicione nextpdf/core ao lado de mpdf/mpdf; mantenha o mPDF instalado por enquanto.
Escolha um documento de baixo risco. Converta new Mpdf([...]) por meio do mapa de configuração e WriteHTML/Output por meio do mapa de verbos.
Registre as fontes que o documento usa em Config->fontsDirectory e adicione declarações explícitas de @font-face/family para qualquer alias do mPDF.
Gere ambos os PDFs para a mesma entrada e compare-os visualmente. Diferenças (substituição de fontes, quebra de linha) são esperadas em mecanismos independentes — aceite-as por documento.
Mapeie qualquer HTML de header/footer para o mecanismo de header/footer do NextPDF.
Repita por documento, do menor risco primeiro; mantenha o mPDF instalado até a última transição.
Remova mpdf/mpdf do composer.json após a transição final.

Testando a migração

Capture a saída do mPDF para documentos representativos antes de alterar o código (entradas golden; os bytes serão diferentes).
Para cada documento migrado, valide a aceitação com a sua própria verificação (comparação visual
- extração de texto). O comportamento de fontes/HTML do NextPDF é exercitado por examples/04-text-and-fonts.php e examples/08-html-basic.php mais as suítes Html/Font do tests/ do núcleo. A aceitação da migração é específica de cada documento e permanece sob a sua responsabilidade.
Adicione um teste de regressão por documento migrado.

Evidências / rastreabilidade

Cada afirmação de comportamento do NextPDF nesta página é respaldada por um teste no repositório, exemplo, assinatura de código-fonte ou registro de decisão de arquitetura (ADR), ou, para propriedades do formato PDF, pelas cláusulas ISO 32000-2 / CSS fixadas via retrieval-augmented generation (RAG) em citations: no front-matter e na tabela de Conformidade. O comportamento do mPDF é descrito apenas como “mecanismo independente — espere diferenças documentadas”; esta página não reivindica nenhuma paridade que um artefato do repositório não prove.

afirmação de comportamento do NextPDF	Evidência no repositório (caminho)
`WriteHTML()` mapeia diretamente para `Document::writeHtml(string $html): static`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)` mapeia para `writeHtmlCell(...)`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` tem como página padrão A4 retrato (`595.276 × 841.890 pt`).	`src/Core/Config.php` (default `PageSize`); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
`Margin` tem ordem de construtor `(top, right, bottom, left)`.	`src/ValueObjects/Margin.php` (ordem das propriedades promovidas).
O destino de saída é o enum `NextPDF\Contracts\OutputDestination`; `'I'/'D'/'F'/'S'` não são aceitos.	`src/Contracts/OutputDestination.php` (cases `Inline`/`Download`/`File`/`String`); `tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php`.
`Output('','S')` → `getPdfData()`; `Output($path,'F')` → `save($path)`.	`src/Core/Concerns/HasOutput.php` (`getPdfData()`, `save()`, `output()`).
`SetProtection()` mapeia para `setEncryption(...)`; as permissões dependem da cooperação do leitor.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (`citations:` do front-matter).
`SetTitle()` → `setTitle()`; os metadados caem no dicionário de informações / XMP.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (`citations:` do front-matter).
As fontes são sempre incorporadas como programas de subset.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (`citations:` do front-matter).
A correspondência / fallback de fontes é específica do mecanismo (diferença de substituição).	CSS Fonts 4 §5.5 (`citations:` do front-matter + Conformidade).
`writeHtml()` é de passagem única; o pico de memória acompanha o tamanho do documento.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Reversão

Ambos os pacotes permanecem instalados até a transição final, portanto a reversão por local de chamada significa reverter aquele local de chamada para o caminho do mPDF. Após a transição final, a reversão significa restaurar mpdf/mpdf e o código anterior a partir do controle de versão. Nenhuma migração de dados está envolvida.

Considerações de desempenho

Consulte Desempenho. O modelo de passagem única elimina o custo do buffer retido do mPDF. O novo custo por documento é a resolução antecipada (eager) de fontes (etapa 3), que pode ser armazenada em cache por meio do diretório de fontes.

Armadilhas comuns

Manter a chave mode e esperar comportamento CJK dela; NextPDF a descarta, e CJK é seleção de fontes.
Passar WriteHTML($html, 2) (modo apenas CSS); em vez disso, embuta o CSS.
Colar HTML de header/footer no corpo.
Esperar que um alias do mPDF resolva para a mesma fonte sem uma família explícita.
Esperar saída byte/pixel-identical (mecanismos independentes — este guia nunca reivindica um drop-in ou 100% de compatibilidade).
Tratar a matriz de suporte a CSS como consultiva; ela é a autoridade de recursos Verificados.