Обзор Backport

Инструмент сборки, а не зависимость времени выполнения. Мейнтейнеры NextPDF используют этот пакет для создания дистрибутивов NextPDF, совместимых с PHP 8.1+ и PHP 7.4+. Приложения никогда не должны добавлять его как зависимость времени выполнения.

Кратко

NextPDF Backport Builder — это инфраструктура сборки для создания дистрибутива экосистемы NextPDF, адаптированного под среды выполнения PHP старше базовой версии разработки. NextPDF написан под современную версию PHP и использует синтаксис, который более ранние интерпретаторы отклоняют. Сборщик пропускает исходный код через Rector — движок, который преобразует абстрактные синтаксические деревья, — и создаёт пакеты с синтаксисом, который принимает среда выполнения PHP 8.1 или PHP 7.4.

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

Имя пакета Composer — nextpdf/backport-builder. Он объявляет "type": "project" и не является зависимостью времени выполнения для NextPDF. В его требования входят только движок сборки (rector/rector), статический анализ (phpstan/phpstan), средство запуска тестов (phpunit/phpunit) и набор пакетов symfony/polyfill-*, используемых в сгенерированном выводе. Файл composer.json в корне репозитория подтверждает это.

Чем этот пакет не является

Этот репозиторий не содержит сам движок NextPDF. В нём находятся правила и скрипты, которые преобразуют этот движок в backport-форму. Такое разделение имеет три практических следствия:

• Вы не устанавливаете его для отрисовки PDF. Установите nextpdf/backport — артефакт, создаваемый этим сборщиком. Оставляйте сборщик на узле сопровождающего или на узле непрерывной интеграции (CI).
• Вы не ведёте разработку на основе сгенерированного кода. Сгенерированный дистрибутив — это машинно созданный артефакт, доступный только для чтения. Отправляйте отчёты об ошибках и запросы новых возможностей в исходные репозитории nextpdf/*.
• Вывод поставляется как теги версий, а не как ветки этого репозитория. Конвейер выпуска помечает сгенерированное дерево тегом и прикрепляет архивы к выпуску GitHub.

Что он создаёт

Сборщик создаёт пакеты Composer, имена и лицензии которых фиксируются файлом scripts/adjust-composer.php:

Созданный пакет	Лицензия	Область	Когда собирается
nextpdf/backport	Apache-2.0	Ядро, адаптеры фреймворков и слой совместимости с tcpdf для целевой версии PHP 8.1	Всегда
nextpdf/backport-pro	proprietary	Модуль Pro, выдаваемый как отдельный пакет	Целевая версия PHP 8.1, когда исходный код Pro присутствует и Pro не исключён

Пакет nextpdf/backport объявляет записи replace Composer, чтобы после установки он удовлетворял ограничениям исходных пакетов. Для целевой версии PHP 8.1 заменяются nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter и nextpdf/compat-legacy. Для целевой версии PHP 7.4 заменяется только nextpdf/core, поскольку сборка для PHP 7.4 содержит только ядро. scripts/adjust-composer.php (buildReplace()) подтверждает это.

Автозагрузчик в потребляющем проекте разрешает объединённое дерево через один префикс PHP Standards Recommendation 4 (PSR-4) — NextPDF\, сопоставленный с src/. PSR-4 сопоставляет префикс пространства имён с базовым каталогом и каждое полностью квалифицированное имя класса — с файлом внутри этого каталога; см. PHP Framework Interop Group (PHP-FIG) PSR-4. Пакет Pro сопоставляет NextPDF\Pro\ со своим собственным src/.

Поддерживаемая матрица PHP

Приведённая ниже матрица охватывает только то, что обеспечивают конфигурации Rector и скрипты сборки. Узел сборки всегда работает на современной версии PHP. Вывод нацелен на более старую.

Аспект	Значение
PHP узла сборки	>=8.4 <9.0
PHP для build/test в CI	8.5
Ограничение вывода для целевой версии PHP 8.1	>=8.1 <8.5
Ограничение вывода для целевой версии PHP 7.4	>=7.4 <8.1
Область целевой версии PHP 8.1	Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, отдельно)
Область целевой версии PHP 7.4	Только ядро

Сборка для PHP 8.1 проверяется на PHP 8.1, 8.2, 8.3 и 8.4. Сборка для PHP 7.4 проверяется на PHP 7.4 и 8.0. Матрицы заданий validate-php81 и validate-php74 в .github/workflows/build.yml подтверждают это. Именно эти среды выполнения задействует конвейер. Это наблюдаемый набор проверок, а не заявление о соответствии.

Модель из двух веток

В этом репозитории нет ветки main. PHP74 — это ветка по умолчанию, а PHP81 — вторая постоянная ветка. Выбранная ветка определяет две вещи: цель по умолчанию для локальной сборки и набор исходного кода, который объединяется. Изменения, затрагивающие обе цели, вносите в каждую ветку отдельным pull request. Рабочий процесс CI выполняется в обеих ветках — PHP74 и PHP81. Это подтверждается командой git branch -a и файлом .github/workflows/0-ci.yml (branches: [PHP74, PHP81]).

Как происходит выпуск

Процесс выпуска управляется событиями. Когда исходная организация NextPDF публикует тег выпуска, событие repository-dispatch с типом source-release запускает рабочий процесс сборки. Рабочий процесс извлекает каждый исходный репозиторий по соответствующему тегу, запускает конвейер, проверяет синтаксис вывода в целевой среде выполнения, проверяет его по всей матрице поддержки и прикрепляет архивы к выпуску GitHub. Тег версии соответствует Semantic Versioning: номер версии — это MAJOR.MINOR.PATCH над объявленным публичным API (Semantic Versioning 2.0.0 §2). .github/workflows/build.yml подтверждает это.

Что дальше

• /integrations/backport/install/ — установка сборщика на узле сборки и установка созданного пакета потребителями.
• /integrations/backport/configuration/ — конфигурации Rector, пользовательские правила и флаги сборки.
• /integrations/backport/quickstart/ — пробный запуск на основе исходного кода и полный вызов сборки.
• /integrations/backport/production-usage/ — встраивание сборщика в рабочий процесс выпуска.
• /integrations/backport/troubleshooting/ — режимы отказа, от которых защищает конвейер, и способы их интерпретации.
• /integrations/backport/security-and-operations/ — состояние цепочки поставок, граница доверия и эксплуатационные гарантии.
• /integrations/backport/boot-and-discovery/ — обнаружение исходных модулей сборщиком и начальная загрузка.
• /integrations/backport/integration/ — контракт интеграции с узлом сборки.