Быстрый старт с compat-legacy

Обзор

На этой странице вы пройдёте путь от установленного пакета до готового PDF, а затем выполните аудит в строгом режиме перед миграцией. Каждый блок кода соответствует поведению, которое проверяет набор тестов пакета, поэтому приведённый здесь вывод совпадает с тем, что проверяют тесты.

Перед началом работы

Установите пакет и проверьте связь с движком по инструкции на странице /integrations/tcpdf-compat/install/. Требуется PHP 8.4; зависимость nextpdf/core ^3.0 должна быть разрешена.

1. Создание первого документа

Замените импорт, но оставьте вызовы в стиле TCPDF. Именно этот интерфейс проверяет tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php.

examples/quickstart-first.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Запустите скрипт:

php examples/quickstart-first.php

Файл quickstart.pdf — корректный PDF 2.0. Набор тестов проверяет, что соответствующий вывод в виде строки начинается с %PDF для назначений S, F и E, а также для getPDFData().

Назначения вывода

Output($name, $dest) сопоставляет коды назначений TCPDF через безопасный мост вывода. Набор тестов проверяет такое поведение:

$dest	Поведение	Возвращает
'S'	Вернуть PDF как строку	байты PDF (%PDF…)
'F'	Записать PDF по указанному пути	пустую строку
'E'	Вернуть MIME-тело в base64	блок Content-Type: application/pdf в ответе
'I'	Встроенное отображение (по умолчанию)	согласно мосту вывода
'D'	Скачивание	согласно мосту вывода

В отличие от устаревшего TCPDF, Output() не выводит данные напрямую в активный буфер вывода. Его можно безопасно вызывать внутри обработчика очереди или HTTP-обработчика, который управляет своим ответом. См. /integrations/tcpdf-compat/production-usage/.

2. Запуск существующего кода TCPDF без изменений

При реальной миграции начните с запуска существующего кода, изменив только импорт или псевдоним. Если ваша кодовая база вызывает new \TCPDF(...) в глобальном пространстве имён, один раз включите дополнительные псевдонимы при загрузке (описано в /integrations/tcpdf-compat/boot-and-discovery/):

examples/quickstart-alias.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Legacy code now resolves \TCPDF to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/aliased.pdf', 'F');

LegacyBootstrap::enableAliases() идемпотентен. Он регистрирует \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS и \TCPDF_IMAGES только если эти классы ещё не существуют. Тест пакета tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php проверяет регистрацию псевдонимов, идемпотентность вызова и то, что new \TCPDF() является экземпляром адаптера. Не включайте псевдонимы, если в том же процессе загружена оригинальная библиотека TCPDF; см. /integrations/tcpdf-compat/troubleshooting/.

3. Аудит в строгом режиме

Этот шаг делает миграцию безопаснее. Когда строгий режим выключен (по умолчанию), методы, которые не могут воспроизвести поведение TCPDF, работают с деградацией без предупреждений. Когда строгий режим включён, они выбрасывают TcpdfNotImplementedException с точным указанием проигнорированных параметров. Запускайте его отдельным проходом аудита, но никогда в рабочей среде.

examples/quickstart-strict-audit.php

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

Тест пакета tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php проверяет, что именно этот вызов выбрасывает исключение в строгом режиме и остаётся без последствий в режиме по умолчанию, а также что сообщение содержит имя метода и проигнорированные параметры. Используйте собранные исключения как список задач миграции — см. /integrations/tcpdf-compat/migration/.

4. Доступ к современному API, когда он вам нужен

Каждый экземпляр адаптера даёт доступ к базовому документу движка. Используйте его для вызова современных методов NextPDF, у которых нет эквивалента в TCPDF:

examples/quickstart-escape-hatch.php

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() возвращает NextPDF\Core\Document, на котором работает адаптер. Это рекомендуемый путь перехода: переносите места вызова на современный API по одному, пока не сможете удалить адаптер.

Различия в поведении, которые вы заметите сразу

• MultiCell() возвращает 1, а не количество отрисованных ячеек. Код, который ветвится в зависимости от возвращаемого значения MultiCell(), требует корректировки.
• Error() выбрасывает RuntimeException вместо вызова die(). Код, который рассчитывал на завершение процесса, должен перехватывать это исключение.
• Точные байты PDF отличаются от вывода TCPDF. Перестройте тесты с побайтовых эталонов на проверку отрисованного содержимого.

Полный список по методам приведён на странице /integrations/tcpdf-compat/method-coverage/.

Дальнейшие шаги

• /integrations/tcpdf-compat/migration/ — полная пофайловая стратегия миграции.
• /integrations/tcpdf-compat/configuration/ — строгий режим, значения по умолчанию и современный объект конфигурации.
• /integrations/tcpdf-compat/production-usage/ — обработчики, буферы вывода и производительность.
• /integrations/tcpdf-compat/security-and-operations/ — подход к шифрованию и подписи.

См. также

• tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — оракул поведения вывода
• tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — оракул строгого режима
• docs/TCPDF_COVERAGE.md — авторитетная матрица покрытия