Быстрый старт с NextPDF Backport Builder

Инструменты сборки — не зависимость времени выполнения. Выполняйте это руководство на хосте сопровождающего разработчика или на хосте непрерывной интеграции (CI). Создаваемый архив используется нижестоящим проектом. Эти шаги никогда не выполняются на сервере приложения.

Кратко

Вы выполняете три команды. Сначала запустите пробный прогон, чтобы проверить, что конвейер настроен правильно и не затрагивает файлы. Затем запустите полную сборку для PHP 8.1. После этого запустите полную сборку для PHP 7.4. В каждом шаге используется одна команда на основе скрипта Composer или документированного вызова scripts/build.php.

Предварительные требования

• Хост сборки с PHP >=8.4 <9.0 и установленными зависимостями сборки (composer install, без --no-dev). См. /integrations/backport/install/.
• Исходные репозитории, извлечённые как соседние каталоги внутри одного корневого каталога исходного кода. Сборка для PHP 8.1 читает nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter и nextpdf-Pro (для Pro). Сборка для PHP 7.4 читает только nextpdf. Проверено по scripts/merge-sources.php.

Шаг 1 — пробный прогон

Пробный прогон выполняет каждый этап в режиме отчёта без изменений. Этап слияния перечисляет файлы, которые он скопировал бы. Команда объявляет Rector, но не запускает его. Этапы генерации composer, копирования ресурсов и проверки описывают свои действия. Ничего не записывается. Запускайте его первым: это самый быстрый способ проверить структуру исходного кода и флаги.

composer build:dry

composer build:dry разворачивается в php scripts/build.php --dry-run. Проверено по composer.jsonscripts и scripts/build.php (ветка dryRun в каждом этапе). С флагами по умолчанию цель — php81, а для корневого каталога исходного кода используется значение скрипта по умолчанию. Любое из этих значений можно переопределить, как показано в шаге 2.

Если пробный прогон сообщает об отсутствующем исходном репозитории, он немедленно останавливается и называет этот репозиторий. Исправьте структуру исходного кода, прежде чем продолжить. См. /integrations/backport/troubleshooting/.

Шаг 2 — полная сборка для PHP 8.1

Сборка для PHP 8.1 выполняет несколько шагов по порядку. Она объединяет ядро с адаптерами фреймворков и слоем совместимости с tcpdf. Затем запускает однопроходную конфигурацию Rector, генерирует nextpdf/backportcomposer.json, копирует лицензию, записывает CHANGELOG.md и подсчитывает количество созданных файлов PHP.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

Проверено по точке входа интерфейса командной строки (CLI) scripts/build.php. Пять этапов выполняются по порядку: слияние исходного кода, понижение версии через Rector, генерация composer.json, копирование статических ресурсов, проверка результата. При успешном выполнении каждый этап выводит галочку. Первый этап, завершившийся с ошибкой, останавливает сборку и выводит свою ошибку. Чтобы исключить Pro, добавьте --no-pro.

При успешном выполнении оркестратор выводит затраченное время и путь к результату. Если включён Pro, он также выводит путь к результату Pro. После этого выходной каталог содержит src/, tests/, сгенерированный composer.json с картой replace и требованиями к полифилам, LICENSE и CHANGELOG.md.

Шаг 3 — полная сборка для PHP 7.4

Сборка для PHP 7.4 включает только ядро и использует двухпроходный конвейер. Она запускает предварительную обработку перечислений, очищает кэш, применяет исправления после Rector, а затем выполняет полное понижение версии.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

Проверено по scripts/build.php. Здесь --target=php74 принудительно ограничивает сборку только ядром, отключает Pro и заставляет runRector() выбрать двухпроходный путь. Сгенерированный composer.json содержит ограничение >=7.4 <8.1. Он заменяет только nextpdf/core и добавляет полифилы для PHP 8.0 и 8.1 поверх полифилов для 8.2–8.5.

Шаг 4 — изучите результат

Этап проверки подсчитывает файлы PHP в output/src и завершается с ошибкой, если их количество равно нулю. Он не выполняет проверку синтаксиса локально: локальный интерпретатор — современный PHP хоста сборки, а не целевая среда выполнения. Вместо этого этап выводит команду Docker для проверки в реальной целевой среде выполнения. Проверено по scripts/build.php (validateOutput()).

Для полной проверки запустите проверку синтаксиса под целевым PHP. Рабочий процесс выпуска идёт тем же путём. Он проверяет синтаксис результата на PHP 8.1 (или PHP 7.4), затем устанавливает и проверяет его на всей матрице поддержки. См. /integrations/backport/production-usage/.

Что вы собрали

Артефакт	Собрано на шаге	Ограничение	Заменяет
nextpdf/backport (PHP 8.1)	Шаг 2	>=8.1 <8.5	модули core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro (PHP 8.1)	Шаг 2, если включён Pro	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (PHP 7.4)	Шаг 3	>=7.4 <8.1	nextpdf/core

Проверено по scripts/adjust-composer.php.

Что дальше

• /integrations/backport/production-usage/ — встройте это в событийно-ориентированный рабочий процесс выпуска.
• /integrations/backport/configuration/ — справочник по правилам и флагам, стоящим за этими командами.
• /integrations/backport/troubleshooting/ — каждый сбой этапа и его значение.