Установка Backport

Устанавливайте этот набор инструментов сборки на рабочей станции сопровождающего или на раннере непрерывной интеграции (CI). Это НЕ зависимость времени выполнения. Приложение-потребитель никогда не устанавливает сборщик; оно устанавливает пакет, который создаёт сборщик.

Кратко

Для двух аудиторий установка различается:

• Сопровождающий или оператор CI клонирует этот репозиторий и устанавливает его зависимости сборки. Устанавливайте nextpdf/backport-builder только в этом контексте.
• Приложение-потребитель в более старой среде выполнения PHP устанавливает сгенерированный пакет nextpdf/backport из своего канала выпуска. Оно никогда не обращается к этому репозиторию.

На этой странице описаны оба рабочих процесса. Прочитайте раздел, соответствующий вашей роли.

Установка на узле сборки

Требования

Зависимость	Ограничение	Источник истины
PHP	>=8.4 <9.0	composer.jsonrequire.php
Composer	2.6+	CONTRIBUTING.md, таблица окружения
rector/rector	^2.0	composer.jsonrequire-dev
phpstan/phpstan	^2.1	composer.jsonrequire-dev
phpunit/phpunit	^13.0	composer.jsonrequire-dev

Рабочий процесс CI подготавливает PHP 8.5 и для сборки, и для задания пробного прогона. Любой узел сборки с версией PHP в диапазоне >=8.4 <9.0 удовлетворяет ограничению Composer. Парсер PHP должен принимать новейший синтаксис, используемый исходным кодом. Проверено по .github/workflows/0-ci.yml.

Шаги

1. Клонируйте репозиторий, затем переключитесь на ветку целевой платформы, которую хотите собрать. PHP74 — это ветка по умолчанию; она создаёт дистрибутив для PHP 7.4, только с ядром. PHP81 создаёт дистрибутив для PHP 8.1 со всеми адаптерами.

   git clone https://github.com/nextpdf-labs/backport.git
   cd backport
   git checkout PHP74

2. Установите зависимости сборки. Не передавайте --no-dev: движок Rector, PHPStan и PHPUnit указаны в require-dev, и без них сборка не сможет выполниться.

   composer install --prefer-dist --no-progress

3. Проверьте, что цепочка инструментов корректно разрешается. Скрипт analyse запускает PHPStan на уровне 10 по rector/rules и scripts. Чистый прогон показывает, что сам код сборки исправен, прежде чем вы создадите результат.

   composer analyse

4. Запустите тесты на фикстурах правил. У каждого пользовательского правила Rector есть набор фикстур, который проверяет точное преобразование before/after.

   composer test

После шага 4 узел готов к сборке. Команды пробного прогона и полной сборки см. в /integrations/backport/quickstart/.

Ожидаемая структура дерева исходного кода

Сборка объединяет несколько исходных репозиториев в одно дерево. Разместите их как соседние каталоги в общем корне исходного кода; скрипт слияния обращается к каждому каталогу по имени. Для целевой платформы 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 (MergeSources::__construct()). Укажите корень исходного кода с помощью --source-dir. Справочник по флагам см. в /integrations/backport/configuration/.

Использование созданного пакета на стороне потребителя

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

PHP с 8.1 по 8.3

composer require nextpdf/backport

Установленный пакет объявляет ограничение >=8.1 <8.5 и заменяет nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter и nextpdf/compat-legacy. Код приложения продолжает импортировать пространство имён NextPDF\ без изменений. Пакет автоматически загружает объединённое дерево через единый префикс PHP Standard Recommendation 4 (PSR-4) NextPDF\, сопоставленный с src/. Автозагрузчик PSR-4 добавляет относительное имя класса к базовому каталогу, зарегистрированному для префикса (PHP-FIG PSR-4). Проверено по scripts/adjust-composer.php (buildPublicAutoloadMap(), buildReplace()).

PHP с 7.4 по 8.0

composer require nextpdf/backport

Дистрибутив для PHP 7.4 содержит только ядро. Он объявляет ограничение >=7.4 <8.1 и заменяет только nextpdf/core. Адаптеры фреймворков, слой совместимости с tcpdf и Pro не включены в дистрибутив для PHP 7.4. Проверено по scripts/adjust-composer.php и scripts/build.php (целевая платформа PHP 7.4 принудительно включает только ядро). Если проекту нужен адаптер фреймворка, требуется PHP 8.1 или новее.

Жизненный цикл поддержки

Целевая платформа PHP 7.4 (только ядро) поддерживается до 2027-12-31, затем поддержка прекращается. Запланируйте переход на PHP 8.1 или новее до этой даты. Минимальная версия PHP 8.1 не зафиксирована: она отслеживает окончание срока поддержки безопасности вышестоящего PHP, поэтому самая младшая поддерживаемая целевая платформа 8.x продвигается по мере достижения версиями PHP окончания срока поддержки безопасности (EOL).

Издание Pro

composer require nextpdf/backport-pro

Дистрибутив Pro — это отдельный пакет, nextpdf/backport-pro, с лицензией proprietary. Он требует nextpdf/backport с совпадающей версией major.minor и добавляет phpseclib/phpseclib ^3.0. Пакет создаётся только для целевой платформы PHP 8.1. Проверено по scripts/adjust-composer.php (generateProComposer()).

Дистрибутив для PHP 7.4 и дистрибутив Pro взаимоисключающи: скрипт сборки не создаёт сборки Pro для PHP 7.4.

Полифилы в созданном пакете

Сгенерированный composer.json требует пакеты symfony/polyfill-*, чтобы более новые функции стандартной библиотеки были доступны в целевой среде выполнения. Целевая платформа PHP 8.1 требует полифилы для PHP 8.2 — 8.5. Целевая платформа PHP 7.4 также требует полифилы для PHP 8.0 и 8.1. Это зависимости времени выполнения созданного пакета, а не сборщика. Проверено по scripts/adjust-composer.php (generatePublicComposer()).

Далее

• /integrations/backport/configuration/ — конфигурация Rector, пользовательские правила и справочник по флагам сборки.
• /integrations/backport/quickstart/ — ваш первый пробный прогон и полная сборка.