Обзор NextPDF Backport Builder
Инструмент сборки, а не зависимость времени выполнения. Мейнтейнеры NextPDF используют этот пакет для создания дистрибутивов NextPDF, совместимых с PHP 8.1+ и PHP 7.4+. Приложения никогда не должны добавлять его как зависимость времени выполнения.
NextPDF Backport Builder — это инфраструктура сборки для создания дистрибутива экосистемы NextPDF, адаптированного под среды выполнения PHP старше базовой версии разработки. NextPDF написан под современную версию PHP и использует синтаксис, который более ранние интерпретаторы отклоняют. Сборщик пропускает исходный код через Rector — движок, который преобразует абстрактные синтаксические деревья, — и создаёт пакеты с синтаксисом, который принимает среда выполнения PHP 8.1 или PHP 7.4.
Имя пакета 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
Заголовок раздела «Поддерживаемая матрица PHP»Приведённая ниже матрица охватывает только то, что обеспечивают конфигурации Rector и скрипты сборки. Узел сборки всегда работает на современной версии PHP. Вывод нацелен на более старую.
| Аспект | Значение | Подтверждение |
|---|---|---|
| PHP узла сборки | >=8.4 <9.0 | composer.jsonrequire.php |
| PHP для build/test в CI | 8.5 | .github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5') |
| Ограничение вывода для целевой версии PHP 8.1 | >=8.1 <8.5 | scripts/adjust-composer.php (generatePublicComposer()) |
| Ограничение вывода для целевой версии PHP 7.4 | >=7.4 <8.1 | scripts/adjust-composer.php (generatePublicComposer()) |
| Область целевой версии PHP 8.1 | Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, отдельно) | scripts/merge-sources.php, scripts/adjust-composer.php |
| Область целевой версии PHP 7.4 | Только ядро | scripts/build.php (--target=php74 принудительно оставляет только ядро, Pro отключён) |
Сборка для 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/ — контракт интеграции с узлом сборки.