Загрузка и обнаружение NextPDF compat-legacy

Краткий обзор

nextpdf/compat-legacy предоставляет NextPDF\Compat\Tcpdf\TCPDF — TCPDF-совместимый фасад, который делегирует работу движку NextPDF. Это слой совместимости, а не совместимый (не byte-identical) клон. Он напрямую делегирует 94 из примерно 120 рассмотренных методов TCPDF 6.x. У остальных методов есть задокументированные различия в поведении; см. /integrations/tcpdf-compat/method-coverage/.

Глобальной привязки во время автозагрузки не происходит. Подключение пакета по умолчанию не создаёт глобальный класс \TCPDF. Глобальные псевдонимы включаются явно; при миграции предпочтительнее импортировать класс адаптера в каждом файле.

Как предоставляется фасад TCPDF

Фасад — это обычный класс, автозагружаемый по стандарту PHP Standard Recommendation 4 (PSR-4):

Элемент	Значение
Класс фасада	NextPDF\Compat\Tcpdf\TCPDF
Префикс PSR-4	NextPDF\Compat\Tcpdf\ сопоставляется с src/Compat/Tcpdf/
Общий контракт	NextPDF\Compat\Contracts\CompatAdapterInterface
Обходной доступ	TCPDF::getDocument() возвращает обёрнутый NextPDF\Core\Document

Класс намеренно не объявлен как final. Пользователи устаревшего TCPDF часто наследуют TCPDF, чтобы переопределить Header() и Footer(), и адаптер сохраняет эту точку расширения. Внутри класс работает как фасад. Он состоит из 25 трейтов с одной зоной ответственности каждый и делегирует все операции с Portable Document Format (PDF) экземпляру Document, созданному при создании фасада.

Последовательность загрузки

Diagram

Создание объекта — единственный шаг “загрузки”. Сам пакет не регистрирует контейнер служб и не выполняет инициализацию фреймворка. Интеграцию с фреймворком вы добавляете отдельно как тонкий слой; см. /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() идемпотентен: он определяет константу только в том случае, если она ещё не определена. Константы, определённые приложением, всегда имеют приоритет, если вы определите их до первого создания объекта; см. /integrations/tcpdf-compat/configuration/ § Порядок разрешения конфигурации.

Необязательные глобальные псевдонимы классов

Если ваш код вызывает new \TCPDF(...) в глобальном пространстве имён и вы пока не можете изменить эти места вызова, зарегистрируйте глобальные псевдонимы один раз при загрузке приложения:

examples/boot-aliases.php

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() регистрирует \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS и \TCPDF_IMAGES. tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php проверяет это поведение:

• enableAliases() идемпотентен: повторный вызов не вызывает исключения и выполняет регистрацию один раз.
• LegacyBootstrap::isRegistered() сообщает, выполнялась ли регистрация.
• После регистрации new \TCPDF() создаёт экземпляр адаптера.

Как избежать конфликтов с реальной установкой TCPDF

Это самое важное правило на этой странице.

enableAliases() регистрирует псевдоним, только если класса с таким именем ещё не существует (class_exists($alias, autoload: false)). Поэтому:

• Если tecnickcom/tcpdf установлен и его \TCPDF загружается первым, псевдоним молча пропускается, и ваш код продолжает использовать устаревший TCPDF, а не адаптер.
• Одновременная работа обеих библиотек с включёнными глобальными псевдонимами в одном процессе не поддерживается и приводит к неоднозначному поведению.

При миграции отдавайте предпочтение явным импортам в каждом файле (use NextPDF\Compat\Tcpdf\TCPDF;). Их легко найти; они не допускают двусмысленности. Удалите tecnickcom/tcpdf после прохождения аудита в строгом режиме; см. /integrations/tcpdf-compat/migration/ Этап 5. Если \TCPDF разрешается не в тот класс, диагностику можно найти в /integrations/tcpdf-compat/troubleshooting/.

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

Пакет не содержит готовых привязок для контейнера фреймворка. Если вы привязываете фасад в контейнере, привяжите фабрику, которая возвращает новый NextPDF\Compat\Tcpdf\TCPDF для каждого документа. Состояние документа связано с экземпляром, поэтому один экземпляр нельзя совместно использовать для несвязанных документов; см. /integrations/tcpdf-compat/production-usage/ § Параллельная обработка. В /integrations/tcpdf-compat/integration/ показана типичная привязка.

Порядок разрешения конфигурации

При создании объекта адаптер разрешает конфигурацию в таком порядке: сначала аргументы конструктора, затем любые существующие устаревшие константы, определённые приложением, а затем значения по умолчанию TCPDF 6.2.13 из LegacyDefaults для каждой константы, которая ещё не определена. Полные сведения и описание современного объекта AdaptationConfig см. в /integrations/tcpdf-compat/configuration/.

Диагностика

Чтобы убедиться, что фасад подключён и связь с движком установлена, создайте адаптер, сформируйте одностраничный PDF и проверьте префикс %PDF. Тесты пакета для вывода проверяют тот же сценарий. Готовая к запуску проверка находится в /integrations/tcpdf-compat/install/ § Проверка установки.

Чтобы обнаружить конфликт с реальным TCPDF до включения псевдонимов, проверьте, существует ли уже глобальный \TCPDF в том месте, где вы собираетесь вызвать enableAliases(). Если он существует, псевдоним будет пропущен. Разрешите конфликт с помощью явных импортов или удалите реальный TCPDF, прежде чем полагаться на адаптер.

Покрытие API TCPDF

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

См. также

• docs/TCPDF_COVERAGE.md — эталонный источник данных о покрытии (в репозитории)
• /integrations/tcpdf-compat/integration/ — подключение фасада к application/framework
• /integrations/tcpdf-compat/method-coverage/ — поведение и пробелы по каждому методу
• /integrations/tcpdf-compat/migration/ — поэтапная стратегия миграции
• /integrations/tcpdf-compat/troubleshooting/ — диагностика конфликтов alias/real-TCPDF
• tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — эталон поведения псевдонимов