Обзор NextPDF compat-legacy
nextpdf/compat-legacy — это TCPDF-совместимая альтернатива: слой совместимости, который предоставляет публичный API TCPDF 6.x поверх движка NextPDF Portable Document Format (PDF) 2.0. У него одна задача: помочь коду, уже зависящему от TCPDF 6.x, запускаться на движке NextPDF без переписывания, чтобы вы могли переносить файл за файлом, а не всё сразу.
Это не форк TCPDF и не гарантированный поведенческий клон. Это независимая реализация, которая сохраняет сигнатуры вызовов TCPDF. Корректнее описывать её так: она покрывает 94 из примерно 120 рассмотренных методов TCPDF 6.x прямым делегированием; для остальных методов задокументированы отличия в поведении (см. /integrations/tcpdf-compat/method-coverage/).
Что это такое
Заголовок раздела «Что это такое»- Средство миграции. Пакет входит в семейство совместимости NextPDF. Он помогает уйти от устаревшей PDF-библиотеки; он не рассчитан на роль постоянной зависимости. Воспринимайте его как временную опору, которую вы уберёте по мере перехода на современный API.
- Адаптер поверхности API. Он предоставляет имя класса TCPDF, имена методов, порядок параметров и значения по умолчанию из версии 6.2.13. Он делегирует вызовы экземпляру
NextPDF\Core\Document. - Независимая реализация, разработанная с нуля. Этот пакет не копирует и не транслирует исходный код TCPDF, артефакты сборки, данные шрифтов или другие материалы, защищённые авторским правом. Имя TCPDF используется только для обозначения совместимости. Каноническая формулировка приведена в файле
NOTICEпакета.
Чем это не является
Заголовок раздела «Чем это не является»- Это не “прямая замена” с байт-идентичным выводом. Для делегируемых методов видимый результат совместим, но байты сформированного PDF отличаются, поскольку в основе работает отдельная независимая реализация PDF 2.0.
- Это не “совместимость с TCPDF на 100%”. Некоторые методы принимают устаревшие параметры, которые движок игнорирует, либо сами ничего не делают. Эти методы перечислены и протестированы — см. /integrations/tcpdf-compat/method-coverage/.
- Сам по себе пакет не является продуктом для подписания или архивирования. Цифровые подписи и соответствие требованиям архивирования PDF/A доступны только в коммерческой редакции NextPDF. Эта документация не заявляет о сертификации, гарантиях или юридической силе подписи.
Зачем мигрировать через слой совместимости
Заголовок раздела «Зачем мигрировать через слой совместимости»Переписывать каждый вызов TCPDF в большом приложении рискованно, а выпускать такую работу постепенно трудно. Слой совместимости позволяет:
- Заменить зависимость, а затем запустить существующий набор тестов, чтобы выяснить, что работает без изменений.
- Использовать строгий режим как средство аудита, которое перечисляет каждое место, где поведение TCPDF невозможно воспроизвести в точности.
- Переносить эти вызовы на современный API NextPDF по одному, чтобы приложение всё время оставалось готовым к выпуску.
Итоговое состояние — современный API NextPDF\Core\Document с удалённым слоем совместимости. Полную стратегию см. в /integrations/tcpdf-compat/migration/.
Что вы получаете на движке NextPDF
Заголовок раздела «Что вы получаете на движке NextPDF»Когда адаптер делегирует вызов TCPDF, этот вызов выполняется на движке PDF 2.0 (ISO 32000-2); при этом доступно шифрование через стандартный обработчик Advanced Encryption Standard (AES)-256, а весь адаптер типобезопасен на уровне PHPStan Level 10. Вывод всегда записывается как PDF 2.0; адаптер не может использовать более старые версии PDF как целевой формат (см. /integrations/tcpdf-compat/method-coverage/ §4).
Адаптер делает безопаснее несколько унаследованных вариантов поведения TCPDF 6.2.13:
| Прежнее поведение | Поведение адаптера |
|---|---|
Error() вызывает die() и молча завершает процесс | Error() выбрасывает RuntimeException: исключение можно наблюдать и перехватывать |
| HTML-метод, который мог выполнять PHP из разметки | Лазейка отключена: разметка не может запускать PHP |
Output() пишет напрямую и может повредить буферы вывода рабочих процессов | Вывод проходит через безопасный мост назначения |
| Незащищённая рекурсия header/footer | Защищена от рекурсии |
Область применения и редакции
Заголовок раздела «Область применения и редакции»Слой совместимости входит в дистрибутив core (nextpdf/compat-legacy, требующий nextpdf/core ^3.0). Шифрование через стандартный обработчик доступно в core. Для цифровых подписей и соответствия требованиям архивирования PDF/A нужна коммерческая редакция NextPDF; адаптер предоставляет точки входа, но путь core не является продуктом для подписания. Точную формулировку см. в /integrations/tcpdf-compat/security-and-operations/.
Что дальше
Заголовок раздела «Что дальше»- /integrations/tcpdf-compat/install/ — установите пакет и проверьте подключение к движку.
- /integrations/tcpdf-compat/quickstart/ — создайте первый рабочий документ, подкреплённый тестами.
- /integrations/tcpdf-compat/method-coverage/ — узнайте, что именно делает здесь каждый метод TCPDF.
- /integrations/tcpdf-compat/migration/ — спланируйте стратегию миграции файл за файлом.
- /integrations/tcpdf-compat/configuration/ — настройте строгий режим и параметры адаптера.
- /integrations/tcpdf-compat/production-usage/ — запускайте адаптер под нагрузкой и в рабочих процессах.
- /integrations/tcpdf-compat/security-and-operations/ — изучите шифрование, статус подписания и усиление защиты.
- /integrations/tcpdf-compat/troubleshooting/ — устраняйте распространённые сбои миграции.
- /integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ — встройте фасад в приложение и зарегистрируйте глобальные псевдонимы классов.
См. также
Заголовок раздела «См. также»docs/TCPDF_COVERAGE.md— каноническая матрица покрытия (в репозитории)- Файл
NOTICEпакета — заявление о независимой реализации