Миграция с устаревших библиотек: TCPDF, FPDF и им подобные

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

Кратко

Если ваши PDF генерируются TCPDF, FPDF, mPDF или dompdf, код, вероятно, всё ещё работает. Именно поэтому проблему легко не заметить. Библиотека запускается, файл открывается, и пробел проявляется лишь в тот день, когда кто-то попросит подписанный, архивируемый или доступный документ, а ответ будет: «отсюда мы этого не можем».

Эта страница — история миграции: что это за стены, почему они структурные, а не случайные, и как NextPDF даёт вам поэтапный путь прочь от них — включая поверхность совместимости с TCPDF, которая является вспомогательным средством миграции, а не обещанием побайтово идентичной замены без изменений кода.

Почему это важно

Библиотека PDF — это не вызов отрисовки, который вы делаете один раз. Это зависимость, которую ваши документы наследуют на всё время своего существования. Когда эта зависимость перестаёт развиваться, ваши документы перестают быть способными делать что-то новое — и вы узнаёте об этом в самый неподходящий момент, когда планку задаёт клиент, аудитор или регулятор.

Стены выглядят так. Формат ушёл вперёд: PDF 2.0 — это текущая редакция стандарта (Spec: ISO 32000-2), и модуль записи, застрявший на структуре 1.x, отстаёт от формата, который предполагает остальная часть вашей цепочки инструментов. Подписание скудно или прикручено сбоку, далеко не дотягивая до базовых профилей PAdES, которые обеспечивают надёжность подписи (Spec: ETSI EN 319 142-1, §4). Архивный вывод в семейство PDF/A и тегированная структура для доступности либо отсутствуют, либо хрупки. А сам API нетипизирован — строковые ориентации, позиционные булевы значения, значения по умолчанию, которые вы обнаруживаете случайно, — так что компилятор не может вам помочь, и рецензент тоже.

Ни одно из этого не является ошибками, которые можно обойти заплаткой. Это форма инструмента, построенного для прошлого десятилетия, и некоторые из этих инструментов больше не движутся активно в сторону стандартов, которым теперь должны соответствовать ваши документы.

Если коротко

Устаревшие PHP-библиотеки для PDF в большинстве своём всё ещё работают. Проблема в том, что они обычно не могут произвести с полным современным соответствием: PDF 2.0, подписи уровня baseline, проверенный PDF/A, тегированную доступность — поддержка среди названных библиотек ограничена или отсутствует.
NextPDF — это движок на PHP 8.4, который пишет PDF 2.0 по умолчанию, со строгими типами, архивными профилями и подписанием PAdES в качестве полноценных выходных результатов.
Вам не нужно переписывать всё в первый же день. Поверхность совместимости с TCPDF позволяет привычным вызовам продолжать работать, пока вы переносите ту логику документов, которая важна.
Эта поверхность совместима с TCPDF, но не побайтово идентична ему. Это мост через миграцию с задокументированными поведенческими отличиями — а не утверждение, что каждый скрипт запускается без изменений.
Честный тест — стоят ли новые возможности этого перехода. Для некоторых нагрузок не стоят, и мы прямо об этом говорим.

Как это реализовано в NextPDF

Подход в том, чтобы сделать миграцию последовательностью, а не скачком. Вы продолжаете производить документы на всём пути и обмениваете старые ограничения по одному, а не ставите релиз на кон ради переписывания «всё сразу».

InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

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.

PDF 2.0 — это базовый уровень, а не флаг функции. NextPDF пишет текущую редакцию формата по умолчанию (Spec: ISO 32000-2) и может сериализовать более старые структуры, когда их запрашивает профиль. Библиотека, замороженная на структуре 1.x, не может встретить вас здесь; это не настройка, которую она упустила, это эпоха, которой она предшествует.

Архивность и доступность — это свойства модуля записи. Произвести файл, который валидатор примет как PDF/A, движок должен в процессе записи — это нельзя приклеить задним числом (Spec: ISO 19005-4). То же верно и для тегированной структуры, которая делает PDF доступным. NextPDF строит их во время генерации, что как раз и есть тот шаг, который многие устаревшие инструменты сделать не могут — или делают лишь частично, не дотягивая до того, что принимает валидатор.

Подписание берёт планку baseline. Усовершенствованные электронные подписи в PDF следуют профилям PAdES (Spec: ETSI EN 319 142-1, §4), где дайджест охватывает объявленный диапазон байтов, а подпись несёт метаданные, которые проверяет валидатор. Прикрученное сбоку средство подписания редко достигает этой планки. NextPDF рассматривает его как полноценный выходной результат, а не как нечто второстепенное.

Поверхность совместимости — это мост, заявленный честно. Слой совместимости с TCPDF существует, чтобы ваши существующие места вызовов продолжали производить документы, пока вы переносите важные части. Он следует той же модели, что и каждое руководство по миграции NextPDF: совместим с исходной библиотекой, но не побайтово идентичен ей, с записанными поведенческими отличиями. Эта честность и есть суть — тихое утверждение «99% замена без изменений» — это тот самый род догадки, отказываться от которого построен этот движок.

Причина мигрировать редко в коде, который у вас есть сегодня; она в документе, который вас попросят завтра. Сопровождаемость — это именованное качественное свойство — насколько легко систему можно анализировать и изменять по мере смены потребностей (Spec: ISO/IEC 25010, §3.6). Зависимость, которая перестала развиваться, тихо его подтачивает, и вы чувствуете цену лишь тогда, когда приходит новое требование, а ответ должен быть «отсюда — нет». Поэтапный переход оплачивает эту цену по вашему графику, пока документы продолжают течь, вместо того чтобы всё сразу под дедлайн.

Практический пример

Форма миграции невелика на месте вызова. Старый код продолжает производить файл через поверхность совместимости; новый код заявляет намерение через типизированный нативный API и запрашивает вывод, которого устаревшая библиотека достичь не может или достигает лишь с ограниченным соответствием.

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

Первый блок — это опора: ничему в вашем приложении не нужно меняться, чтобы документы продолжали течь. Второй — это пункт назначения: типизированный вызов, где «portrait», «string output» и шрифт явны, и где архивность, подписание и доступность становятся выходами, которые можно включить, а не стенами, в которые вы упираетесь.

Распространённое заблуждение

Частая надежда — «должен же быть флаг, который заставит мою старую библиотеку делать PDF 2.0 и подписи». Его нет. Это не опции, которые зрелая библиотека забыла открыть; это возможности, вокруг которых её архитектура никогда не строилась. Вы не можете настройкой добраться до редакции формата или профиля подписи, которые модуль записи не реализует.

Зеркальное заблуждение — что NextPDF является 100% заменой TCPDF без изменений, так что миграция бесплатна. Это не так, и мы не будем притворяться, что это иначе. Поверхность совместимости покрывает реальный, задокументированный срез API, чтобы перенести вас через переход; некоторые вызовы ведут себя иначе, а немногие — вне области охвата. Относитесь к этому как к мосту с опубликованной картой, а не как к гарантии, что каждый устаревший скрипт запускается без правок.

Ограничения и границы

TCPDF-compatibility surface as a migration aid — edition availability
Edition	Availability
Core	Поверхность совместимости совместима с TCPDF, но не побайтово идентична ему. Она покрывает задокументированное подмножество API, чтобы существующие места вызовов продолжали производить файлы во время миграции. Это мост, а не замена без изменений: некоторые поведения отличаются, а некоторые вызовы не поддерживаются — всё перечислено на страницах покрытия методов и миграции. Пункт назначения — это нативный типизированный API, где живёт вывод уровня стандартов.
Pro	Available
Enterprise	Available

Миграция — это средство, а не добродетель. Если ваши документы просты, ваша библиотека по-прежнему сопровождается, и вам никогда не понадобятся PDF 2.0, подписание, PDF/A или доступность, честный ответ может быть таким: остаться там, где вы есть — стоимость перехода реальна, и переход, который вам не нужен, — это переход, который вам не следует делать. Страница про когда не стоит использовать NextPDF проводит эту черту не дрогнув.

Эта страница описывает путь миграции и цели движка. Точное покрытие API, поведенческие отличия и пошаговая процедура живут в документации по совместимости, которая является авторитетом в том, что делает каждый вызов. Ничто здесь не обещает, что произвольный устаревший скрипт запустится без изменений.

Связанные документы

Что изменил PDF 2.0 — редакция формата, которую многие устаревшие библиотеки не могут выдать, и почему это важно.
Поверхность совместимости с TCPDF — авторитетное руководство по тому, что покрывает мост и где он отличается.
Когда не стоит использовать NextPDF — честная граница, чтобы миграцию, которая вам не нужна, можно было пропустить.
Один движок, каждый фреймворк — куда движок, на который вы мигрируете, встраивается в стек, который вы уже используете.

Глоссарий

PDF 2.0 — текущая редакция стандарта Portable Document Format (ISO 32000-2). Раскрывается при первом упоминании; формат, который NextPDF пишет по умолчанию.
PDF/A — семейство архивного соответствия (серия ISO 19005), которое определяет, что делает PDF безопасным для долгосрочного хранения. Свойство, которое модуль записи должен произвести, а не то, что вызывающий может добавить позже.
PAdES — PDF Advanced Electronic Signatures, семейство профилей ETSI (EN 319 142) для встраивания подписей уровня стандартов в PDF. Раскрывается при первом упоминании; подробно рассмотрено на страницах о подписании.
Поверхность совместимости — слой API, имеющий форму исходной библиотеки (здесь — TCPDF), который позволяет существующим местам вызовов продолжать работать во время миграции. Совместим с оригиналом, но не побайтово идентичен ему — мост, а не замена без изменений.
Замена без изменений (drop-in replacement) — заместитель, который запускает существующий код без правок. Поверхность совместимости с TCPDF намеренно не описывается так; это задокументированное вспомогательное средство миграции с известными поведенческими отличиями.