Миграция с mPDF на NextPDF

Кратко

Это руководство помогает перенести кодовую базу на основе mPDF на ядро NextPDF. В mPDF основной вызов для вывода содержимого — WriteHTML(), и он напрямую соответствует Document::writeHtml(). Основная работа сводится к сопоставлению массива конфигурации конструктора (mPDF настраивает всё через один ассоциативный массив, передаваемый в new Mpdf([...])) и учёту различий в обработке шрифтов. NextPDF и mPDF — независимые движки, поэтому перенесённый документ совместим с выводом mPDF, но не идентичен ему побайтно. Это руководство охватывает сопоставление методов, массив конфигурации, различия в шрифтах, поддержку CSS, поведенческие различия и безопасную последовательность действий.

Эта матрица поддержки CSS определяет, какие возможности HTML и CSS проверены. Руководство описывает поведение; оно не заявляет визуальной эквивалентности с mPDF.

Установка

composer require nextpdf/core:^3

Оставьте mpdf/mpdf установленным на время переноса. Удалите его после финального переключения (см. безопасную последовательность переноса).

Концептуальный обзор

Объект Mpdf в mPDF объединяет конфигурацию и отрисовку в одном интерфейсе. Массив конструктора задаёт настройки, а WriteHTML() вместе с методами разбивки на страницы (AddPage, SetHTMLHeader, SetHTMLFooter) управляют выводом. NextPDF выносит конфигурацию в неизменяемый объект-значение NextPDF\Core\Config и записывает содержимое через Document::writeHtml(). Строки “режима” конструктора нет. NextPDF разбирает переданный HTML, а затем формирует документ через save(), output() или getPdfData().

Шрифты: mPDF поставляется с каталогом шрифтов, картой fontdata и резервным набором “основных шрифтов”. NextPDF разрешает шрифты из одного каталога шрифтов и через сопоставление CSS font-family, а также всегда создаёт подмножества встроенных шрифтов (Международная организация по стандартизации (ISO) 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Сопоставление и подстановка шрифтов зависят от движка (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13), поэтому подстановка глифов может отличаться. Это основное заметное различие; оно рассмотрено в разделе различие в обработке шрифтов.

Поверхность API

HTML-API NextPDF описан в справочнике по модулю Html. Основные точки входа — Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string и объект-значение NextPDF\Core\Config.

Сопоставление методов API

Имена публичных методов mPDF ниже сверены с публичным upstream-репозиторием (mpdf/mpdf, development); см. сопроводительный файл происхождения _source-sidecar-upstream-api.md в репозитории. Текст upstream-документации не воспроизводится.

mPDF	NextPDF	Примечания
`new Mpdf([...])`	`Document::createStandalone($config)`	Массив конфигурации mPDF сопоставляется с `NextPDF\Core\Config`; см. карту конфигурации. Для долгоживущих процессов используйте `DocumentFactory`.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	Прямое соответствие. Второй аргумент `$mode` в mPDF (полный документ, только CSS или элемент) не имеет аналога в NextPDF; передавайте полный HTML.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	Позиционированная область HTML заданного размера; сопоставьте аргументы x/y/ширина/высота.
`$mpdf->AddPage(...)`	`$doc->addPage()`	NextPDF не принимает аргументы для переопределения orientation/format/полей на каждый вызов, как mPDF; вместо этого изменяйте модель документа между вызовами.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	header/footer через Layout API	Сквозные HTML-колонтитулы mPDF соответствуют механизму header/footer в NextPDF, а не HTML, встроенному в начало тела документа.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	Символы назначения mPDF (`I`/`D`/`F`/`S`) соответствуют перечислению `OutputDestination` (`Inline`/`Download`/file через `save()`/string через `getPdfData()`).
`$mpdf->Output('','S')`	`$doc->getPdfData()`	Возвращает байты.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	Записывает по пути к файлу.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	Значение попадает в словарь информации о документе ISO 32000-2 §14 / XMP (`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (Security API — API безопасности)	Разрешения зависят от взаимодействия со средством просмотра, а не являются контролем доступа — см. примечания по безопасности.

Пример кода — Быстрый старт

<?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";

Пример кода — Продакшн

Этот пример согласован с examples/04-text-and-fonts.php — запускаемой основой для концепций обработки шрифтов в этом руководстве. В нём используются явный размер страницы, поля и тело документа, в котором задействован выбор шрифтов.

<?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);

Граничные случаи и подводные камни

Аргумент $mode у WriteHTML. WriteHTML($html, $mode) в mPDF (2 = только CSS, 1 = элемент) не имеет эквивалента. Поместите CSS в передаваемый HTML; последовательности “сначала записать CSS, затем тело” не существует.
Переопределения на каждый AddPage. mPDF позволяет AddPage() менять format/orientation в середине документа с помощью аргументов. NextPDF addPage() не принимает таких аргументов; изменение размера моделируется через документ, а не через вызов страницы.
HTML колонтитулов. mPDF регистрирует сквозные колонтитулы как отдельные фрагменты HTML; не вставляйте их в тело документа. Сопоставьте их с механизмом header/footer в NextPDF.
Имена шрифтов. mPDF нормализует имена шрифтов через таблицу fontdata/core-font. NextPDF сопоставляет CSS font-family с каталогом шрифтов; псевдоним mPDF, который разрешался неявно, может потребовать явного @font-face/family.
Символы назначения. 'I'/'D'/'F'/'S' не принимаются; используйте перечисление OutputDestination или save()/getPdfData().

Производительность

writeHtml() работает в один проход (ADR-001); пиковая память зависит от размера документа, а не от удерживаемой объектной модели документа (DOM). Бюджет для примера из этого руководства: wall_ms: 2000, peak_mb: 128. Для длинных документов разбивайте содержимое по вызовам addPage(), а не передавайте одну огромную строку. По смыслу это те же рекомендации, что применяются к разбиению на части через $mode в mPDF, но выражены через модель страниц.

Примечания по безопасности

Разрешения зависят от взаимодействия со средством просмотра. SetProtection() → setEncryption() обеспечивает конфиденциальность, а не контроль доступа: биты разрешений ISO зависят от того, как их интерпретирует средство просмотра. Не представляйте шифрование пользователям как контроль доступа.
Метаданные. SetTitle() и информация о документе попадают в словарь информации о документе ISO 32000-2 §14 / XMP (iso32000_2_sec14#x1.x5.p5); никогда не храните там секреты.
NextPDF не выполняет встроенные в документ сценарии; никакая директива mPDF этого не меняет.

Соответствие

Утверждение	Спецификация	Пункт
Шрифты записываются как embedded/subset программы шрифтов.	ISO 32000-2	§9
Параметры страницы format/margins сопоставляются с граничным боксом страницы.	ISO 32000-2	§7
Метаданные заголовка / защиты попадают в словарь информации о документе / XMP.	ISO 32000-2	§14
Сопоставление и подстановка шрифтов зависят от движка.	CSS Fonts 4	§5.5

NextPDF производит содержимое ISO 32000-2; он не утверждает визуальной идентичности с mPDF. Повторно проверяйте вывод при каждой смене рендерера.

Коммерческий контекст

Неприменимо. Ядро NextPDF покрывает описанный здесь путь перехода с mPDF.

См. также

Подробности перехода (обязательные разделы R6)

Для кого это

Команды, использующие mpdf/mpdf для серверного преобразования HTML в PDF. Если ваш код построен вокруг new Mpdf([...]) + WriteHTML + Output (+ необязательный header/footer), этот сценарий покрывают карта методов и карта конфигурации.

Область охвата

В области охвата: массив конфигурации конструктора Mpdf, WriteHTML/Output/AddPage, headers/footers, шрифты, защита, метаданные. Вне области охвата: внутренние классы mPDF и вспомогательные возможности быстрого отклика (QR)/barcode/watermark. Сопоставьте их с соответствующими модулями NextPDF — Barcode и Graphics, — которые здесь не рассматриваются.

Карта совместимости

Поведенческая совместимость, а не готовая прослойка: NextPDF не предоставляет прослойку класса Mpdf. Перепишите каждую точку вызова. Для ожиданий по возможностям CSS используйте проверенные строки матрицы поддержки CSS.

Сопоставление массива конфигурации конструктора

Ключи конфигурации mPDF ниже сверены с публичным upstream-репозиторием (mpdf/mpdf, development). Текст upstream-документации не воспроизводится.

Ключ конфигурации mPDF	NextPDF	Примечания
`mode`	(нет эквивалента)	Строка режима mPDF (`'utf-8'`, `'c'`, `'+aCJK'`, …) выбирает поведение font/script. NextPDF всегда работает в Unicode; текст на китайском, японском и корейском языках (CJK) обрабатывается через выбор шрифтов, а не через режим. Удалите этот ключ.
`format`	`Config->pageSize` (объект-значение (VO) `PageSize`)	Именованные форматы преобразуются в явные размеры в пунктах; массивы `[w,h]` сопоставляются с `PageSize`.
`orientation`	поменять местами `PageSize` width/height	Флага ориентации нет; альбомная означает, что ширина > высоты.
`default_font_size`	базовый размер шрифта CSS	Задайте его в базовой таблице стилей, а не ключом конструктора.
`default_font`	CSS `font-family` / зарегистрированный шрифт	Задайте семейство по умолчанию через CSS / регистрацию шрифтов.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (VO `Margin`) в пунктах	Используйте один объект-значение `Margin`; порядок его конструктора — `Margin(top, right, bottom, left)` (сверьте по `src/ValueObjects/Margin.php`), а не порядок ключей mPDF.
`margin_header` / `margin_footer`	смещение header/footer через Layout API	Сопоставьте их с конфигурацией header/footer в NextPDF, а не с ключами конструктора.

Различие в обработке шрифтов

Единый каталог шрифтов. Список каталогов шрифтов mPDF, карта fontdata и резерв основных шрифтов сводятся к Config->fontsDirectory плюс сопоставление по CSS font-family.
Всегда подмножества. NextPDF всегда создаёт подмножества встроенных шрифтов (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); флаги подмножеств mPDF не имеют эквивалента и не нужны.
Сопоставление зависит от движка. Сопоставление и подстановка шрифтов различаются в зависимости от движка (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); псевдониму шрифта mPDF может потребоваться явное @font-face или точное имя семейства. Заново зафиксируйте эталон отрисовки глифов после перехода. Различия в подстановке ожидаемы и не являются дефектами.

Поведенческие различия

Подстановка шрифтов (см. выше) — основное заметное различие.
Нет $mode у WriteHTML — передавайте полный HTML со встроенным CSS.
Нет переопределения формата на каждый AddPage — изменение размера моделируется через документ.
Разрешения зависят от взаимодействия со средством просмотра (см. примечания по безопасности).
Независимый движок макета — перенос строк / разбивка на страницы различаются на плотном содержимом; заново зафиксируйте эталон визуальных различий.

Это документированные поведенческие различия, а не дефекты ни одного из движков.

Не поддерживается / нет прямого эквивалента

mode — строка конструктора, не моделируется (всегда Unicode).
Аргументы format/orientation/margin на каждый AddPage() — в NextPDF не передаются аргументами.
Карта fontdata mPDF — заменена каталогом шрифтов + сопоставлением по CSS.
Символы назначения 'I'/'D'/'F'/'S' в mPDF — заменены перечислением OutputDestination + save()/getPdfData().

Безопасная последовательность переноса

Добавьте nextpdf/core рядом с mpdf/mpdf; пока оставьте mPDF установленным.
Выберите один документ с низким риском. Преобразуйте new Mpdf([...]) по карте конфигурации, а WriteHTML/Output — по карте методов.
Зарегистрируйте используемые документом шрифты в Config->fontsDirectory и добавьте явные объявления @font-face/family для любого псевдонима mPDF.
Сгенерируйте оба PDF для одного и того же входа и визуально сравните их. Различия (подстановка шрифтов, перенос строк) ожидаемы для независимых движков — принимайте их для каждого документа.
Сопоставьте любой HTML header/footer с механизмом header/footer в NextPDF.
Повторяйте для каждого документа, начиная с наименее рискованных; сохраняйте mPDF установленным до последнего переключения.
Удалите mpdf/mpdf из composer.json после финального переключения.

Тестирование перехода

Сохраните снимок вывода mPDF для репрезентативных документов до изменения кода (эталонные входные данные; байты будут отличаться).
Для каждого перенесённого документа подтверждайте приёмку собственной проверкой (визуальное сравнение
- извлечение текста). Поведение NextPDF в работе со шрифтами/HTML задействуется в examples/04-text-and-fonts.php и examples/08-html-basic.php, а также в наборах тестов Html/Font ядра tests/. Приёмка перехода зависит от конкретного документа и остаётся вашей ответственностью.
Добавьте регрессионный тест для каждого перенесённого документа.

Доказательства / прослеживаемость

Каждое утверждение о поведении NextPDF на этой странице подкреплено тестом, примером, сигнатурой исходного кода или записью об архитектурном решении (ADR) в репозитории, либо — для свойств формата PDF — пунктами ISO 32000-2 / CSS, закреплёнными через RAG, в поле фронтматтера citations: и таблице Соответствие. О поведении mPDF говорится только как о “независимом движке — ожидайте документированных различий”; эта страница не заявляет паритета, который не доказан артефактом в репозитории.

Утверждение о поведении NextPDF	Доказательство в репозитории (путь)
`WriteHTML()` напрямую соответствует `Document::writeHtml(string $html): static`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)` соответствует `writeHtmlCell(...)`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` — страница по умолчанию A4 книжной ориентации (`595.276 × 841.890 pt`).	`src/Core/Config.php` (`PageSize` по умолчанию); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
`Margin` — порядок конструктора `(top, right, bottom, left)`.	`src/ValueObjects/Margin.php` (порядок свойств конструктора).
Назначение вывода — перечисление `NextPDF\Contracts\OutputDestination`; `'I'/'D'/'F'/'S'` не принимаются.	`src/Contracts/OutputDestination.php` (варианты `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()` соответствует `setEncryption(...)`; разрешения зависят от взаимодействия со средством просмотра.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (фронтматтер `citations:`).
`SetTitle()` → `setTitle()`; метаданные попадают в словарь информации о документе / XMP.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (фронтматтер `citations:`).
Шрифты всегда встраиваются как программы-подмножества.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (фронтматтер `citations:`).
Сопоставление и подстановка шрифтов зависят от движка (различие в подстановке).	CSS Fonts 4 §5.5 (фронтматтер `citations:` + Соответствие).
`writeHtml()` работает в один проход; пиковая память зависит от размера документа.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Откат

Оба пакета остаются установленными до финального переключения, поэтому откат для отдельной точки вызова означает возврат этой точки вызова к реализации mPDF. После финального переключения откат означает восстановление mpdf/mpdf и предыдущего кода из системы контроля версий. Миграция данных не требуется.

Соображения о производительности

См. Производительность. Однопроходная модель устраняет затраты на удержание буфера mPDF. Новые затраты на каждый документ — это предварительное разрешение шрифтов (шаг 3), которое можно кешировать через каталог шрифтов.

Распространённые ошибки

Сохранение ключа mode и ожидание от него поведения CJK; NextPDF отбрасывает его, а CJK обрабатывается через выбор шрифтов.
Передача WriteHTML($html, 2) (режим только CSS); вместо этого используйте встроенный CSS.
Вставка HTML header/footer в тело документа.
Ожидание, что псевдоним mPDF разрешится в тот же шрифт без явного семейства.
Ожидание byte/pixel-identical вывода (независимые движки — это руководство никогда не заявляет о готовой замене или 100%-й совместимости).
Отношение к матрице поддержки CSS как к рекомендательной; она является авторитетным источником по проверенным возможностям.