Интеграция NextPDF compat-legacy

Кратко

Используйте nextpdf/compat-legacy, чтобы подключить приложение и запускать существующий код TCPDF 6.x на движке NextPDF. Этот пакет — вспомогательное средство миграции, а не постоянная прослойка; удалите его после перехода на современный API приложения (см. /integrations/tcpdf-compat/migration/). Это TCPDF-совместимая альтернатива, а не совместимый (не byte-identical) клон: 94 из ~120 рассмотренных методов TCPDF делегируются напрямую. Для остальных методов задокументированы различия в поведении (см. /integrations/tcpdf-compat/method-coverage/).

Установка

composer require nextpdf/compat-legacy:^3.0

При этом Composer транзитивно разрешает nextpdf/core ^3.0. Полный список требований и проверку корректности см. в /integrations/tcpdf-compat/install/.

Загрузка и автообнаружение

Пакет не регистрирует глобальные сущности при автозагрузке. Его подключение не создаёт глобальный \TCPDF. Вы сами выбираете, как этот класс будет разрешаться в местах вызова:

Предпочтительно (явные импорты). Замените строки use/require на use NextPDF\Compat\Tcpdf\TCPDF; в каждом файле. Так поведение однозначно, а вызовы легко искать.
Глобальные псевдонимы по запросу. Вызовите LegacyBootstrap::enableAliases() один раз при загрузке, чтобы зарегистрировать \TCPDF и четыре вспомогательных класса — только если эти имена ещё не заняты. Описание механизма, идемпотентности и правила разрешения конфликтов с настоящим TCPDF: /integrations/tcpdf-compat/boot-and-discovery/.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

Привязки контейнера

Пакет не включает поставщика сервисов или бандл для фреймворка. Тонкий слой интеграции вы реализуете сами. Привяжите фабрику, которая возвращает новый адаптер для каждого документа, а не общий синглтон: каждый экземпляр хранит состояние документа (см. /integrations/tcpdf-compat/production-usage/ § Concurrency).

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

В Symfony зарегистрируйте фабрику как сервис без совместного использования (non-shared). В Laravel используйте bind (а не singleton), чтобы при каждом разрешении создавался новый экземпляр. Сам пакет остаётся независимым от фреймворка.

Публикация конфигурации

Публикуемого файла конфигурации для фреймворка нет. Настраивайте адаптер через устаревшие константы K_* / PDF_* (определите их в загрузчике до первого создания экземпляра) или через современный неизменяемый объект NextPDF\Compat\Tcpdf\Config\AdaptationConfig. См. /integrations/tcpdf-compat/configuration/.

Дымовой тест поставщика сервисов / бандла

После подключения убедитесь, что интеграция создаёт корректный файл Portable Document Format (PDF). Это повторяет область поведения, проверяемую в tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

$bytes = $pdf->Output('smoke.pdf', 'S');

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

В контексте Hypertext Transfer Protocol (HTTP) или фонового обработчика используйте Output(..., 'F') или 'S'. Не полагайтесь на inline-вывод. Полное руководство по эксплуатации см. в /integrations/tcpdf-compat/production-usage/.

Точки входа публичного API

Точка входа	Назначение
`NextPDF\Compat\Tcpdf\TCPDF`	TCPDF-совместимый фасад. Создавайте отдельный экземпляр для каждого документа.
`TCPDF::getDocument()`	Возвращает обёрнутый `NextPDF\Core\Document` — путь к современному API.
`TCPDF::setStrictMode(bool)`	Переключатель аудита миграции (см. /integrations/tcpdf-compat/configuration/).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	Глобальные псевдонимы классов по запросу.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	Современный неизменяемый объект конфигурации.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	Общий контракт совместимости.

Покрытие API TCPDF

Эталонная, проверенная тестами матрица покрытия находится в файле репозитория docs/TCPDF_COVERAGE.md. Сводка для читателя — зеркалируемые, молча игнорируемые, нереализованные и неприменимые методы — находится в /integrations/tcpdf-compat/method-coverage/. Не называйте это реализацией “совместимой (не byte-identical) заменой” или “совместимой на 100 %”. Описывайте это как TCPDF-совместимую альтернативу с известной, протестированной поверхностью и задокументированными различиями в поведении.

См. также

docs/TCPDF_COVERAGE.md — эталонный источник данных о покрытии в репозитории
/integrations/tcpdf-compat/boot-and-discovery/ — предоставление фасада и поведение псевдонимов
/integrations/tcpdf-compat/method-coverage/ — поведение и пробелы по каждому методу
/integrations/tcpdf-compat/migration/ — поэтапная стратегия миграции
/integrations/tcpdf-compat/production-usage/ — как запускать адаптер под нагрузкой
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — эталон (oracle) поведения вывода