Миграция с TCPDF

Это руководство проведёт вас через миграцию существующего проекта с устаревшего TCPDF (tecnickcom/tcpdf) на TCPDF-Next. TCPDF-Next — это полная переработка, а не прямая замена, но процесс миграции систематичен и чётко определён.

Ключевые различия

Возможность	TCPDF (устаревший)	TCPDF-Next
Версия PHP	5.3+	8.5+
Версия PDF	PDF 1.7	PDF 2.0
Архитектура	Один монолитный класс (~27 000 строк)	17 модульных пространств имён, 142 класса
Стиль API	Процедурный, PascalCase методы	Fluent builder, camelCase методы
Типобезопасность	Нет типов	declare(strict_types=1), enums, readonly
Статический анализ	Нет	PHPStan Level 10, ноль ошибок
Шифрование	RC4, AES-128, AES-256	Только AES-256 (PDF 2.0 Revision 6)
Подписи	Базовый PKCS#7	PAdES B-B до B-LTA
PDF/A	PDF/A-1b (частично)	PDF/A-4 (полный ISO 19005-4)
Перекрёстные ссылки	Устаревшие xref-таблицы	Потоки перекрёстных ссылок
Обработка шрифтов	Проприетарный бинарный формат	Стандартный TTF/OTF, автоматический subsetting
Парсинг HTML	На основе Regex (ограниченный)	На основе DOM (улучшенная поддержка CSS)
Зависимости	Ноль	Ноль

Маппинг API: старые методы на новые

Наиболее заметное изменение — поверхность API. TCPDF-Next использует camelCase, именованные параметры, value objects и fluent builders:

Устаревший TCPDF	TCPDF-Next	Примечания
new TCPDF()	Document::create()	Fluent builder, именованные параметры
$pdf->Cell()	$pdf->cell()	camelCase
$pdf->MultiCell()	$pdf->multiCell()	camelCase
$pdf->SetFont()	$pdf->setFont()	camelCase
$pdf->SetDrawColor()	$pdf->setDrawColor()	camelCase
$pdf->Output('file.pdf', 'F')	$pdf->save('file.pdf')	Явный метод
$pdf->Output('file.pdf', 'I')	$pdf->output('file.pdf', OutputDestination::Inline)	На основе Enum

Создание документа

$pdf = new TCPDF('P', 'mm', 'A4', true, 'UTF-8', false); 
$pdf->SetCreator('My App'); 
$pdf->SetAuthor('John Doe'); 
$pdf->SetTitle('Invoice #12345'); 
$pdf->SetKeywords('invoice, payment, monthly'); 
$pdf->setPrintHeader(false); 
$pdf->setPrintFooter(false); 
$pdf->SetMargins(15, 15, 15); 
$pdf->SetAutoPageBreak(true, 15); 
$pdf->AddPage(); 
use YeeeFang\TcpdfNext\Document\PdfDocument; 
use YeeeFang\TcpdfNext\Document\PageFormat; 
use YeeeFang\TcpdfNext\Document\Orientation; 
use YeeeFang\TcpdfNext\Document\Margins; 
$pdf = PdfDocument::create() 
    ->setCreator('My App') 
    ->setAuthor('John Doe') 
    ->setTitle('Invoice #12345') 
    ->setKeywords(['invoice', 'payment', 'monthly']) 
    ->setPageFormat(PageFormat::A4) 
    ->setOrientation(Orientation::PORTRAIT) 
    ->setMargins(Margins::uniform(15)) 
    ->setAutoPageBreak(true, bottomMargin: 15) 
    ->build(); 
$page = $pdf->addPage(); 

Изменение конфигурации: константы на Enums

Устаревший TCPDF использовал целочисленные константы и магические строки. TCPDF-Next использует PHP 8.1+ enums:

// TCPDF: Магические целые числа для режима шифрования
$pdf->SetProtection(['print', 'copy'], 'user', 'owner', 3); 

// TCPDF-Next: Типобезопасные enums
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY | Permissions::COPY) 
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->apply(); 

Обработка цвета: массивы на Color Value Objects

// TCPDF: Простые целочисленные массивы
$pdf->SetDrawColor(255, 0, 0); 
$pdf->SetFillColor(0, 128, 255); 

// TCPDF-Next: Color value objects
use YeeeFang\TcpdfNext\Color\Color; 
$canvas->setStrokeColor(Color::rgb(255, 0, 0)); 
$canvas->setFillColor(Color::rgb(0, 128, 255)); 
$canvas->setFillColor(Color::hex('#0080FF')); 
$canvas->setFillColor(Color::cmyk(100, 50, 0, 0)); 

Размер страницы: строки на PageSize Value Objects

// TCPDF: Магические строки
$pdf = new TCPDF('P', 'mm', 'A4'); 
$pdf->AddPage('L', 'LETTER'); 

// TCPDF-Next: Типобезопасные enums и value objects
use YeeeFang\TcpdfNext\Document\PageFormat; 
use YeeeFang\TcpdfNext\Document\Orientation; 
$pdf = PdfDocument::create() 
    ->setPageFormat(PageFormat::A4) 
    ->build(); 
$page = $pdf->addPage(PageFormat::LETTER, Orientation::LANDSCAPE); 
$custom = $pdf->addPage(PageFormat::custom(100, 200)); // mm

Шифрование: RC4/AES-128 на только AES-256

TCPDF-Next удаляет все устаревшие алгоритмы шифрования. Если ваше приложение использует RC4 или AES-128, вы должны обновиться до AES-256:

// TCPDF: Несколько алгоритмов (включая небезопасные)
$pdf->SetProtection(['print'], 'user', 'owner', 0); // RC4-40 -- НЕБЕЗОПАСНО
$pdf->SetProtection(['print'], 'user', 'owner', 1); // RC4-128 -- НЕБЕЗОПАСНО
$pdf->SetProtection(['print'], 'user', 'owner', 2); // AES-128
$pdf->SetProtection(['print'], 'user', 'owner', 3); // AES-256

// TCPDF-Next: Только AES-256 (единственный безопасный вариант)
$pdf->setEncryption() 
    ->setAlgorithm(EncryptionAlgorithm::AES256) // Only option
    ->setUserPassword('user') 
    ->setOwnerPassword('owner') 
    ->setPermissions(Permissions::PRINT_HIGH_QUALITY) 
    ->apply(); 

WARNING

PDF, зашифрованные с помощью RC4 или AES-128 устаревшим TCPDF, должны быть повторно зашифрованы с AES-256. Шифрование RC4 не обеспечивает реальной безопасности — существуют инструменты для его взлома за секунды.

Чек-лист критических изменений

Просмотрите этот чек-лист перед началом миграции:

• [ ] Требуется PHP 8.5+ — Обновите среду выполнения PHP. PHP 7.x и 8.0-8.4 не поддерживаются.
• [ ] Смена пространства имён — Замените ссылки на класс TCPDF на пространства имён YeeeFang\TcpdfNext\....
• [ ] camelCase методы — SetFont() становится setFont(), MultiCell() становится multiCell() и т.д.
• [ ] Конструктор заменён — new TCPDF(...) становится PdfDocument::create()->...->build().
• [ ] Метод Output заменён — Output('file.pdf', 'F') становится save('file.pdf').
• [ ] Изменение формата шрифтов — Замените бинарные файлы шрифтов TCPDF (.php + .z) на оригинальные файлы TTF/OTF.
• [ ] Методы Header/Footer — Замените наследование класса (extends TCPDF) на callback-и событий (onPageHeader()).
• [ ] Обновление шифрования — RC4 и AES-128 удалены. Мигрируйте на AES-256.
• [ ] Массивы цветов — Замените простые массивы [255, 0, 0] на Color::rgb(255, 0, 0).
• [ ] Строковые размеры страниц — Замените строки 'A4' на значения enum PageFormat::A4.
• [ ] Формат ключевых слов — Измените строку с разделителями-запятыми на массив: 'a, b' становится ['a', 'b'].
• [ ] Параметр единиц удалён — TCPDF-Next по умолчанию использует миллиметры (настраивается для каждого документа).
• [ ] Возвращаемые типы — Многие методы теперь возвращают типизированные результаты вместо void. Используйте возвращаемые значения #[\NoDiscard].

Слой совместимости (постепенная миграция)

Для больших кодовых баз TCPDF-Next предоставляет слой совместимости, отображающий большинство устаревших вызовов методов:

// Замените ваш импорт — существующий код продолжает работать
use YeeeFang\TcpdfNext\Compat\TcpdfCompat as TCPDF;

Слой совместимости покрывает примерно 80% публичного API TCPDF. Неподдерживаемые методы выбрасывают DeprecatedMethodException с указанием современного эквивалента.

WARNING

Слой совместимости — это средство миграции, а не постоянное решение. Он добавляет накладные расходы и не раскрывает продвинутые возможности TCPDF-Next (подписи PAdES, PDF/A-4, потоки перекрёстных ссылок). Планируйте завершить миграцию на нативный API.

Полный маппинг API

Для исчерпывающего справочника по методам, охватывающего 30+ методов, смотрите Таблицу маппинга API.

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

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