Руководство разработчика по адаптеру совместимости с TCPDF

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

Адаптер совместимости — это миграционный слой. Он не скрывает устаревшее поведение, а делает его явным. Используйте его, чтобы приложение продолжало работать, пока вы переводите наиболее важные пути на нативные API NextPDF.

Используйте это руководство, если вы поддерживаете устаревший код в стиле TCPDF, расширяете покрытие адаптера или планируете поэтапную миграцию на нативные API NextPDF.

Архитектурные границы

Слой	Принадлежит	Зона ответственности	Не размещать здесь
Устаревшее приложение	Приложение	Поддержание работоспособности существующих вызовов в стиле TCPDF во время миграции.	Новые возможности PDF, которые должны использовать нативные API NextPDF.
Оболочка адаптера	nextpdf/compat-legacy	Предоставление класса в стиле TCPDF и общего состояния совместимости.	Крупные семейства методов или логика преобразования.
Трейты областей ответственности	nextpdf/compat-legacy	Группировка устаревших семейств методов: текст, шрифты, изображения, безопасность, формы, страницы.	Политика вывода, затрагивающая несколько семейств методов.
Классы-мосты	nextpdf/compat-legacy	Преобразование устаревших аргументов, мест назначения, цветов, единиц измерения и форматов.	Поведение, зависящее от бизнес-логики.
Основной движок	nextpdf/nextpdf	Создание нативного документа.	Обязательства по поддержке совместимости с устаревшим кодом.

Жизненный цикл выполнения

Этап	Поведение	Действие разработчика
Начальная загрузка	Необязательная начальная загрузка для устаревшего кода предоставляет имена совместимости.	Используйте её только там, где устаревший код ожидает наличия символов TCPDF.
Создание объекта	Адаптер сопоставляет устаревшие аргументы конструктора с конфигурацией основного документа.	Сохраняйте входные данные конструктора стабильными во время миграции.
Вызов метода	Поддерживаемые методы сопоставляются с поведением NextPDF через области ответственности и мосты.	Прежде чем рассчитывать на паритет, проверьте покрытие методов.
Неподдерживаемая возможность	Адаптер выбрасывает явные исключения совместимости для неподдерживаемого поведения.	Замените вызов или изолируйте его на уровне кода приложения.
Вывод	Мост вывода сопоставляет устаревшее поведение мест назначения с механизмом вывода NextPDF.	Проверяйте имена файлов и корневые каталоги хранилища.

Инвентаризация миграции

Начните со сбора всех вызовов методов TCPDF в вашем приложении. Классифицируйте каждый вызов, перед тем как менять поведение.

Классификация	Значение	Действие
Поддерживаемый метод адаптера	Метод документирован как поддерживаемый и имеет тесты.	Временно оставьте его, а затем мигрируйте, когда будете работать с этой областью.
Частично поддерживаемый метод адаптера	Метод существует, но его поведение не полностью соответствует устаревшему TCPDF.	Добавьте тесты с фикстурами и проверьте вывод вручную.
Явно неподдерживаемый метод	Адаптер выбрасывает исключение совместимости.	Замените его нативным API NextPDF или удалите эту возможность.
Обёртка, специфичная для бизнес-логики	В приложении уже есть обёртка для вызовов TCPDF.	Сначала мигрируйте внутреннюю реализацию обёртки.
Вызов, критичный для соответствия требованиям	Подпись, шифрование, тегирование, PDF/A, доступность или процесс выставления счетов.	Мигрируйте на нативные API NextPDF и проведите отдельную проверку.

Шаблон внесения изменений в адаптер

Добавляйте поддержку совместимости в самое узкое семейство методов, отвечающее за это поведение.

Тип изменения	Где реализовать	Обязательный тест
Метод вывода текста	Concerns\AdaptsTextOutput или область ответственности шрифтов.	Фикстура устаревшего поведения и проверка нативного вывода.
Метод страницы или полей	Область ответственности страницы, позиционирования или полей.	Тест преобразования координат и состояния страницы.
Метод изображения или рисования	Область ответственности изображений, рисования, цвета или градиентов.	Тест проверки входных данных и visual/structural вывода.
Место назначения вывода	OutputBridge.	Тест сопоставления мест назначения и небезопасных путей.
Неподдерживаемая возможность	Фабрика исключений или таблица покрытия методов.	Тест типа исключения и его сообщения.

Если за это семейство отвечает трейт области ответственности, не помещайте крупный метод непосредственно в оболочку адаптера.

Шаблон миграции на нативный код

Используйте адаптер для стабилизации устаревшего кода, а затем переводите стабильные рабочие процессы на нативные API.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Рассматривайте миграцию как последовательность небольших изменений поведения. Страница может продолжать использовать адаптер, пока отдельный раздел с высоким риском переводится на нативные API.

Точки расширения

Точка расширения	Используйте для	Ограничение
AdaptationConfig	Управление поведением адаптера во время миграции.	Сохраняйте значения по умолчанию явными и проверенными.
Трейты областей ответственности	Группировка семейств методов, например текста, форм, изображений или безопасности.	Добавляйте методы в соответствующую область ответственности, а не в оболочку адаптера.
Классы-мосты	Преобразование устаревших форм аргументов в значения ядра.	Покрывайте поведение мостов миграционными тестами.
CompatAdapterInterface	Абстракция уровня адаптера для инструментов.	Не используйте её в новом коде как замену нативных контрактов ядра.
Таблица покрытия методов	Запись о статусе поддержки для разработчиков.	Обновляйте её при изменении статуса поддержки.

Рабочий процесс миграции

1. Установите адаптер и запустите устаревший набор тестов без изменений.
2. Откройте покрытие методов и классифицируйте каждый вызываемый метод.
3. Сначала замените неподдерживаемые методы.
4. Переведите пути с высокой нагрузкой или критичные для соответствия требованиям на нативные API ядра.
5. Добавьте покрытие фикстурами для каждого мигрированного семейства методов.
6. Удаляйте псевдонимы начальной загрузки, когда ни одна точка входа приложения от них не зависит.

Обработка сбоев

Сбой	Где обрабатывать	Рекомендуемая реакция
Неподдерживаемый метод	Исключение адаптера.	Замените вызов или изолируйте его на уровне адаптера приложения.
Частичный паритет макета	Миграционные тесты и визуальная проверка.	Задокументируйте принятое отличие перед развёртыванием.
Небезопасное место назначения вывода	OutputBridge и политика хранилища приложения.	Отклоняйте небезопасные пути и предпочитайте нативные API вывода.
Несоответствие функций безопасности	План миграции на нативный код.	Не выпускайте для регулируемых выходных документов поведение, основанное только на совместимости.
Конфликт псевдонимов начальной загрузки	Начальная загрузка приложения.	Удалите глобальные псевдонимы или ограничьте их областью устаревших точек входа.

Безопасные значения по умолчанию

Область ответственности	Значение по умолчанию	Когда переопределять
Неподдерживаемые методы	Выбрасывать явное исключение.	Не ослабляйте это поведение в рабочей среде.
Устаревшие значения по умолчанию	Централизовано в LegacyDefaults.	Переопределяйте только ради известного поведения миграции.
Сопоставление вывода	Проходит через OutputBridge.	После миграции используйте нативные API вывода.
Источник покрытия	Страница покрытия методов и тесты.	Перезапускайте проверки покрытия после каждого обновления адаптера.
Строгий режим	Оставляйте включённым во время аудитов миграции.	Отключайте только в рамках задокументированного окна совместимости с устаревшим кодом.

Контрольный список тестирования

• Сохраняйте фикстуру устаревшего поведения для каждого мигрированного семейства методов.
• Добавьте один нативный тест NextPDF, прежде чем заменять устаревший метод.
• Проверяйте, что неподдерживаемые методы выбрасывают задокументированное исключение.
• Сравнивайте структуру вывода, когда точное побайтовое равенство не является реалистичной целью миграции.
• Запускайте проверки покрытия методов после добавления или изменения методов адаптера.
• Добавляйте тесты путей хранилища для каждого места назначения вывода, используемого устаревшим кодом.