Миграция с mPDF

Это руководство поможет вам мигрировать с mPDF (mpdf/mpdf) на TCPDF-Next. mPDF — это библиотека HTML-в-PDF с широкой поддержкой CSS и такими функциями, как CJK-текст, штрих-коды и водяные знаки. TCPDF-Next предлагает расширенный набор возможностей mPDF с соответствием современным стандартам и нулевыми зависимостями времени выполнения.

Сравнение возможностей

Возможность	mPDF	TCPDF-Next
Версия PHP	7.4+	8.5+
Версия PDF	PDF 1.4 / 1.7	PDF 2.0
Архитектура	Ориентирован на HTML/CSS	PDF-нативная с поддержкой HTML
Зависимости времени выполнения	10+ пакетов Composer	Ноль
Шифрование	RC4, AES-128, AES-256	Только AES-256 (PDF 2.0)
Цифровые подписи	Не поддерживается	PAdES B-B до B-LTA
PDF/A	PDF/A-1b, PDF/A-3b (частично)	PDF/A-4 (полный ISO 19005-4)
Tagged PDF	Ограниченно	Полная доступность PDF/UA
Поддержка CJK	Да (встроенные 50+ МБ шрифтов)	Да (регистрация собственных, оптимизированный subsetting)
RTL / BiDi	Да	Да (совместимо с UAX #9)
Штрих-коды	Да (1D и 2D)	Да (нативные векторные, расширенный набор)
Водяные знаки	Да	Да
Генерация оглавления	Да	Да
Использование памяти	Высокое (полный DOM в памяти)	Умеренное (потоковый вывод)

Специфичные функции mPDF и эквиваленты TCPDF-Next

Пользовательские HTML-теги

mPDF определяет нестандартные HTML-теги. Они требуют адаптации:

Пользовательский тег mPDF	Эквивалент TCPDF-Next
<tocpagebreak>	$pdf->addTableOfContentsPage()
<tocentry content="..." level="0">	$toc->addEntry('...', level: 0)
<barcode code="..." type="C128">	$page->addBarcode(BarcodeFactory::code128('...'))
<columnbreak>	$renderer->columnBreak()
<pagebreak>	<div style="page-break-before: always"> (стандартный CSS)
<bookmark content="...">	$pdf->addBookmark('...')
<watermarktext content="DRAFT">	$pdf->setWatermark(Watermark::text('DRAFT'))
<watermarkimage src="...">	$pdf->setWatermark(Watermark::image('...'))

HTML-заголовки и колонтитулы

mPDF (до):

$mpdf->SetHTMLHeader('<div style="text-align: center;">Header</div>');
$mpdf->SetHTMLFooter('<div>Page {PAGENO} of {nbpg}</div>');
$mpdf->SetHTMLHeader('<div>Even header</div>', 'E');

TCPDF-Next (после):

$pdf->setHtmlHeader('<div style="text-align: center;">Header</div>');
$pdf->setHtmlFooter('<div>Page {{pageNumber}} of {{totalPages}}</div>');
$pdf->setHtmlHeader('<div>Even header</div>', pages: 'even');

Режимы WriteHTML

mPDF (до):

$mpdf->WriteHTML($css, \Mpdf\HTMLParserMode::HEADER_CSS);
$mpdf->WriteHTML($body, \Mpdf\HTMLParserMode::HTML_BODY);

TCPDF-Next (после):

$renderer = new HtmlRenderer($pdf);
$renderer->addStylesheet($css);
$renderer->writeHtml($body);

Водяные знаки

mPDF (до):

$mpdf->SetWatermarkText('DRAFT', 0.1);
$mpdf->showWatermarkText = true;

TCPDF-Next (после):

$pdf->setWatermark(
    Watermark::text('DRAFT')
        ->setOpacity(0.1)
        ->setRotation(45)
        ->setColor(Color::rgb(200, 200, 200))
);

Маппинг конфигурации

Конфигурация mPDF	Эквивалент TCPDF-Next
mode => 'utf-8'	Всегда UTF-8 (конфигурация не нужна)
format => 'A4'	setPageFormat(PageFormat::A4)
margin_left/right/top/bottom	setMargins(new Margins(...))
default_font	$renderer->setDefaultFont(...)
tempDir	PdfDocument::create()->setTempDir(...)
autoScriptToLang	$renderer->setAutoFontDetection(true)
biDirectional	Всегда включено (UAX #9)
pdfaAuto	setPdfALevel(PdfALevel::PDF_A_4)

Методы вывода

mPDF (до):

$mpdf->Output('/path/to/file.pdf', \Mpdf\Output\Destination::FILE);
$mpdf->Output('doc.pdf', \Mpdf\Output\Destination::DOWNLOAD);
$mpdf->Output('doc.pdf', \Mpdf\Output\Destination::INLINE);
$content = $mpdf->Output('', \Mpdf\Output\Destination::STRING_RETURN);

TCPDF-Next (после):

$pdf->save('/path/to/file.pdf');
$bytes = $pdf->toString();

// Web-ответ (пример Laravel)
return response($pdf->toString(), 200, [
    'Content-Type' => 'application/pdf',
    'Content-Disposition' => 'attachment; filename="doc.pdf"',
]);

Сокращение зависимостей

Миграция с mPDF значительно упрощает дерево зависимостей:

Удалено (mPDF + транзитивные):

• mpdf/mpdf + 10+ транзитивных пакетов
• psr/log, psr/http-message, setasign/fpdi, mpdf/qrcode

Добавлено:

• yeee-fang/tcpdf-next (ноль зависимостей времени выполнения)

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

Метрика	mPDF	TCPDF-Next	Улучшение
Простой 1-страничный PDF	45,3 мс	8,2 мс	В 5,5x быстрее
100-страничный документ	3 210 мс	845 мс	В 3,8x быстрее
Пиковая память (1 стр.)	18,4 МБ	4,2 МБ	В 4,4x меньше
Пиковая память (100 стр.)	198,2 МБ	28,6 МБ	В 6,9x меньше
Размер выходного файла (1 стр.)	24,3 КБ	12,4 КБ	В 2,0x меньше

Полную методологию и тест-кейсы смотрите в Бенчмарках производительности.

Дополнительные материалы

• Таблица маппинга API — Полный маппинг методов
• Бенчмарки — Полное сравнение производительности с mPDF
• Справочник API — Полная документация API TCPDF-Next
• FAQ — Частые вопросы по миграции