Справочник API совместимости с TCPDF
Пакет nextpdf/compat-legacy предоставляет один основной класс — NextPDF\Compat\Tcpdf\TCPDF. Он повторяет публичный программный интерфейс (API) TCPDF 6.x, но выполняет отрисовку с помощью современного движка NextPDF. Пакет также включает небольшую вспомогательную поверхность: LegacyBootstrap для глобальных псевдонимов классов, поверхность конфигурации AdaptationConfig/LegacyDefaults, внутренние классы-мосты для вывода, конструирования, цвета, единиц измерения и форматов страниц, а также исключения совместимости. Используйте его как средство миграции, а не как постоянную зависимость. Полный статус устаревших методов смотрите в таблице покрытия методов. Эта страница описывает только те поверхности API, на которые код приложения должен опираться намеренно.
Начните здесь: если вы впервые работаете с этим пакетом, создайте экземпляр NextPDF\Compat\Tcpdf\TCPDF, выполните привычные вызовы TCPDF (AddPage(), SetFont(), Cell()) и завершите вызовом Output($name, $dest). Этот класс — точка входа почти ко всему, что описано ниже. Готовые отправные примеры см. в разделе Типовые задачи.
Типовые задачи
Заголовок раздела «Типовые задачи»С этими задачами пакета вы будете работать чаще всего. Каждый блок сверен с исходным кодом адаптера и выполняется без изменений.
Создайте файл в формате Portable Document Format (PDF) привычными вызовами TCPDF, а затем получите его в виде строки для очереди, ответа HTTP или хранилища:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\TCPDF;
$pdf = new TCPDF('P', 'mm', 'A4');$pdf->SetTitle('Invoice 1234');$pdf->SetFont('helvetica', '', 12);$pdf->AddPage();$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');
$bytes = $pdf->Output('invoice.pdf', 'S');Что это делает: создаёт документ PDF 2.0 через адаптер в форме TCPDF. Он возвращает необработанные байты (%PDF...), потому что назначение 'S' направляет вызов через OutputBridge к Document::getPdfData() вместо вывода в поток. Поэтому такой вызов безопасен внутри обработчика или контроллера.
Зарегистрируйте глобальные псевдонимы один раз при загрузке, чтобы существующий код new \TCPDF(...) выполнялся без изменений в исходном коде:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\LegacyBootstrap;
LegacyBootstrap::enableAliases();
$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter$pdf->AddPage();$pdf->Cell(0, 10, 'Legacy call site, modern engine');$pdf->Output(__DIR__ . '/legacy.pdf', 'F');Что это делает: enableAliases() идемпотентно регистрирует \TCPDF (а также вспомогательные \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES помощники), только если эти имена ещё не определены. После этого неизменённый устаревший код работает через адаптер.
Проверьте миграцию, выявив каждый параметр TCPDF, который адаптер иначе молча проигнорировал бы:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;use NextPDF\Compat\Tcpdf\TCPDF;
$pdf = new TCPDF();$pdf->setStrictMode(true);$pdf->AddPage();$pdf->SetFont('helvetica', '', 12);
try { $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);} catch (TcpdfNotImplementedException $e) { fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter}Что это делает: при setStrictMode(true) вызов, который не может воспроизвести поведение TCPDF, выбрасывает TcpdfNotImplementedException и перечисляет каждый проигнорированный параметр. Это превращает молчаливую деградацию в перечень работ по миграции. Включайте это только во время аудита, никогда в продакшене.
Основной адаптер
Заголовок раздела «Основной адаптер»Эта таблица — каноническая поверхность адаптера. В ней указаны класс, который вы создаёте (TCPDF), его методы строгого режима и аварийного доступа, а также контракт, который он реализует.
| Символ | Параметры | Поведение по умолчанию | Возвращает | Выбрасывает или завершается с | Примечания |
|---|---|---|---|---|---|
NextPDF\Compat\Tcpdf\TCPDF | Параметры конструктора следуют форме устаревшего TCPDF через ConstructorBridge. | Создаёт адаптер на базе документа NextPDF. | TCPDF | Исключения при валидации конструктора или из-за неподдерживаемой возможности. | Используйте для миграции, но не для нового нативного кода NextPDF. |
TCPDF::getDocument() | нет. | Возвращает базовый документ NextPDF. | NextPDF\Core\Document | не ожидается. | Используйте как аварийный выход для кода миграции, которому нужно совмещать устаревшие и нативные вызовы. |
TCPDF::getUnitConverter() | нет. | Возвращает преобразователь, созданный на основе устаревшей единицы измерения. | UnitConverter | не ожидается. | Используйте для диагностики миграции, а не для обычного кода приложения. |
TCPDF::setStrictMode(bool $enabled) | Флаг строгого режима. | Включает или отключает явный сбой при неподдерживаемом поведении совместимости. | static | не ожидается. | Держите включённым во время аудитов миграции. |
TCPDF::isStrictMode() | нет. | Возвращает текущий флаг строгого режима. | bool | не ожидается. | Полезно в проверках тестов. |
TCPDF устаревшие методы | Зависит от метода. | Поддерживаемые методы сопоставляются с вызовами основного документа; неподдерживаемые методы завершаются явным сбоем. | Зависит от метода. | TcpdfNotImplementedException или UnsupportedFeatureException. | Прежде чем полагаться на метод, проверьте покрытие методов. |
CompatAdapterInterface::getDocument() | нет. | Метод контракта, реализованный в TCPDF. | Document | не ожидается. | Позволяет инструментам обращаться к нативному документу. |
CompatAdapterInterface::Output(string $name = '', string $dest = '') | Имя файла и устаревшее назначение. | Делегирует мосту вывода. | string | Ошибки записи в ядре или неподдерживаемого назначения. | Повторяет поведение вывода устаревшего TCPDF; конкретный TCPDF::Output задаёт значения по умолчанию 'doc.pdf'/'I'. |
Группы устаревших методов
Заголовок раздела «Группы устаревших методов»Эта таблица сопоставляет семейства методов TCPDF, которые покрывает адаптер. Просмотрите её, чтобы найти устаревший вызов перед проверкой его точного статуса в покрытии методов.
| Группа | Характерные символы | Поведение по умолчанию | Примечания |
|---|---|---|---|
| Жизненный цикл и вывод | Open(), Close(), Output(), getPDFData() | Поддерживает жизненный цикл документа в форме TCPDF поверх нативного документа. | После миграции предпочитайте нативные API вывода. |
| Метаданные | SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator() | Сопоставляет сеттеры метаданных с базовым документом. | Выполняйте нормализацию метаданных в коде приложения. |
| Страницы и позиционирование | AddPage(), setPage(), lastPage(), GetX(), SetXY() | Преобразует устаревшие единицы измерения и координаты в нативные операции со страницами. | После миграции визуально проверьте абсолютное позиционирование. |
| Поля и макет | SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins() | Сохраняет состояние совместимости и сопоставляет поддерживаемые значения. | Сложное поведение разрыва страниц TCPDF может потребовать ручной проверки. |
| Шрифты и текст | SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text() | Передаёт распространённые операции с текстом в нативные API шрифтов и текста. | Проверьте поведение CJK и кодировок с рабочими шрифтами. |
| HTML | writeHTML(), writeHTMLCell(), fixHTMLCode() | Передаёт поддерживаемый HTML в нативный HTML-конвейер. | Нативный отрисовщик не является полным клоном HTML-движка TCPDF. |
| Изображения и рисование | Image(), Line(), Rect(), Circle(), SetDrawColor() | Сопоставляет поддерживаемые графические операции через средства адаптера. | Неподдерживаемые векторные или специальные форматы завершаются явным сбоем. |
| Навигация и аннотации | Bookmark(), AddLink(), SetLink(), Annotation() | Сохраняет распространённые навигационные вызовы, если для них есть сопоставление. | Проверьте созданные структуры и ссылки. |
| Безопасность и подписи | SetProtection(), setSignature(), setTimeStamp(), setUserRights() | Связывает поддерживаемые устаревшие вызовы безопасности с нативными возможностями. | Рассматривайте криптографический вывод как отдельный этап проверки. |
| Формы, шаблоны, преобразования | TextField(), startTemplate(), StartTransform(), Rotate(), Scale() | Реализует поддерживаемые подмножества и явно завершается с ошибкой при неподдерживаемом поведении. | Перед развёртыванием сверьте каждый вызов с покрытием методов. |
Начальная загрузка и конфигурация
Заголовок раздела «Начальная загрузка и конфигурация»Используйте эту таблицу, когда встраиваете адаптер в путь начальной загрузки приложения, регистрируете глобальные псевдонимы или выбираете между устаревшими константами и современным AdaptationConfig.
| Символ | Параметры | Поведение по умолчанию | Возвращает | Выбрасывает или завершается с | Примечания |
|---|---|---|---|---|---|
LegacyBootstrap::enableAliases() | нет. | Регистрирует псевдонимы совместимости один раз. | void | Ошибки автозагрузки или окружения. | Используйте только тогда, когда устаревший код ожидает глобально доступные имена TCPDF. |
LegacyBootstrap::isRegistered() | нет. | Сообщает, зарегистрированы ли псевдонимы. | bool | не ожидается. | Полезно в тестах начальной загрузки. |
LegacyBootstrap::resetForTesting() | нет. | Очищает состояние регистрации для тестов. | void | не ожидается. | Помощник только для тестов. |
AdaptationConfig | Флаги адаптера и средства управления миграцией. | При отсутствии значений использует значения пакета по умолчанию. | AdaptationConfig | Недопустимые значения параметров. | Во время аудитов миграции задавайте конфигурацию явно. |
AdaptationConfig::fromLegacyConstants() | нет. | Считывает известные устаревшие константы и строит объект конфигурации. | AdaptationConfig | Недопустимые значения устаревших констант. | Переходный помощник для больших устаревших приложений. |
LegacyDefaults | нет. | Предоставляет устаревшие значения по умолчанию. | Значения по умолчанию. | не ожидается. | Единое место для значений совместимости по умолчанию. |
Мосты и помощники
Заголовок раздела «Мосты и помощники»Эти внутренние классы преобразования обеспечивают работу адаптера. Используйте эту таблицу, когда расширяете покрытие адаптера или диагностируете, как был преобразован устаревший аргумент. Для повседневного кода приложения предпочитайте публичную поверхность адаптера.
| Символ | Параметры | Поведение по умолчанию | Возвращает | Выбрасывает или завершается с | Примечания |
|---|---|---|---|---|---|
ConstructorBridge | Список аргументов устаревшего конструктора. | Нормализует устаревшие параметры в конфигурацию NextPDF. | Данные конструктора. | Недопустимые значения устаревших аргументов. | Используется внутри адаптера. |
CellParameterAdapter | Параметры ячейки TCPDF. | Сопоставляет устаревшие позиционные аргументы с параметрами компоновки текста ядра. | Адаптированные параметры. | Недопустимые размеры или выравнивание. | В новом коде предпочитайте нативные методы ядра. |
OutputBridge::dispatch(Document $document, string $filename, string $dest) | Нативный документ, имя файла и устаревшее назначение. | Сопоставляет поведение inline/download/save с API вывода NextPDF. | string | Ошибки записи в ядре; неподдерживаемое назначение. | Перед выводом проверяйте имена файлов и корневые каталоги хранилища. |
OutputBridge::resolveDestination(string $dest) | Код устаревшего назначения. | Преобразует назначение в нативное назначение вывода. | OutputDestination | Ошибки неподдерживаемого назначения. | Хранит сопоставление назначений в одном месте. |
ColorTranslator | Аргументы цвета TCPDF. | Нормализует устаревшие формы записи цвета. | Значение цвета ядра. | Недопустимые значения цвета. | Используется средствами цвета и рисования. |
PageFormatResolver | Входные данные устаревшего формата страницы. | Сопоставляет известные имена с размерами страниц ядра. | Значение формата страницы. | Неизвестный формат. | После миграции используйте явные нативные размеры страниц. |
UnitConverter | Устаревшие значения измерений и единицы измерения. | Преобразует в единицы измерения ядра. | Числовое значение. | Недопустимая единица измерения. | Помогает сохранить устаревшее поведение макета. |
Исключения
Заголовок раздела «Исключения»Используйте эту таблицу, когда вызов во время миграции завершается с явной ошибкой. Она разделяет сбои “не реализовано” и “известно, но не поддерживается” и показывает путь восстановления.
| Символ | Значение | Восстановление |
|---|---|---|
TcpdfNotImplementedException | Адаптер намеренно не реализует запрошенный устаревший метод. | Замените вызов нативным API NextPDF или удалите зависимость. |
TcpdfNotImplementedException::forSilentIgnore() | Устаревший вызов ранее был бы проигнорирован, но теперь сообщается явно для ясности миграции. | Решите, приемлемо ли явное отсутствие операции. |
TcpdfNotImplementedException::forUnimplemented() | Для устаревшего вызова нет реализованного пути адаптера. | Замените вызов или изолируйте его за кодом миграции. |
UnsupportedFeatureException | Устаревшая возможность известна, но не поддерживается в рамках адаптера. | Сверьтесь с указаниями по миграции и изолируйте возможность за адаптером приложения. |
UnsupportedFeatureException::forMethod() | Создаёт ошибку неподдерживаемой возможности для конкретного метода. | Используйте при доработке совместимости, чтобы сообщения об ошибках оставались единообразными. |
Заметки для разработчиков
Заголовок раздела «Заметки для разработчиков»- Рассматривайте адаптер как инструмент миграции. Новый код должен напрямую использовать основные API NextPDF.
- Неподдерживаемое поведение должно завершаться с явной ошибкой. Не перехватывайте исключения совместимости и не продолжайте работу с частичным документом, если приложение явно не принимает этот риск.
- Вносите миграционные изменения небольшими шагами и сверяйте каждый устаревший метод с таблицей покрытия.