Устранение неполадок в сборщике бэкпортов NextPDF

Инструменты сборки — НЕ зависимость времени выполнения. Каждый симптом на этой странице относится к состоянию на этапе сборки на хосте сопровождающего или в непрерывной интеграции (CI). Ни одно из этих состояний не возникает в приложении-потребителе.

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

Сборка выполняет пять последовательных этапов. Она останавливается на первом сбое и выводит имя этапа и сообщение. Посмотрите имя этапа, затем найдите ниже соответствующую причину. Этапы: слияние исходников, понижение версии через Rector, генерация composer.json, копирование статических ресурсов и проверка вывода. Сверено с scripts/build.php (run() и step()).

Этап: слияние исходников

Ошибка «Source repo '' not found at: »

Перед копированием файлов этап слияния проверяет наличие каждого ожидаемого исходного репозитория. Если репозиторий отсутствует, сборка прерывается и выводит его имя и путь. Целевая платформа PHP 8.1 ожидает nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter и — когда включён Pro — nextpdf-Pro. Целевая платформа PHP 7.4 ожидает только nextpdf. Сверено с scripts/merge-sources.php (цикл проверки run(), карта репозиториев __construct()).

Решение: разместите репозитории как соседние каталоги по пути, переданному в --source-dir, и используйте точные имена каталогов, указанные выше. Пробный запуск перечисляет все репозитории, которые он прочитал бы. Используйте его, чтобы проверить структуру каталогов перед полной сборкой.

Этап: запуск понижения версии через Rector

Rector завершается с ненулевым кодом

Оркестратор сообщает Rector failed on <label> (exit code: N) и останавливается. Метка показывает, какой проход завершился сбоем: public package, pro package, enum pre-processing или full downgrade. Сверено с scripts/build.php (runRectorPass()).

Сбой распознавателя параметров по умолчанию на значениях перечислений по умолчанию (PHP 7.4)

Именно поэтому целевая платформа PHP 7.4 использует два прохода. Распознаватель значений параметров по умолчанию в Rector аварийно завершается, когда вариант перечисления используется как значение по умолчанию в promoted-свойстве конструктора. Проход 1 (rector-php74-enums.php) сначала преобразует перечисления в классы со списком констант. После этого полный проход в проходе 2 уже не встречает вариант перечисления как значение по умолчанию. Если обойти оркестратор и запустить полную конфигурацию PHP 7.4 напрямую на исходниках с перечислениями, ожидайте этого сбоя. Сверено с scripts/build.php (комментарий runRector() и последовательность из двух проходов) и rector/config/rector-php74-enums.php.

Скрипты бенчмарков аварийно завершают Rector

rector-php81.php и rector-php74.php пропускают */tests/Benchmark/*. Эти скрипты ссылаются на внешние библиотеки Portable Document Format (PDF), которые Rector не может разрешить; из-за этого сбоит распознаватель параметров по умолчанию. Если путь бенчмарка обрабатывается, значит шаблон пропуска отсутствует или путь отличается. Сверено с вызовами withSkip().

`MHASH_XXH*` — сбой (PHP 7.4)

rector-php74.php пропускает DowngradeHashAlgorithmXxHashRector. Это встроенное правило аварийно завершается на константах xxHash. Исходный код не использует xxHash, поэтому пропуск безопасен. Сверено с rector/config/rector-php74.php (withSkip()).

Этап: исправления после Rector (только PHP 7.4)

Эти исправления выполняются между двумя проходами. Они переписывают шаблоны, оставленные правилом преобразования перечислений в классы. Если в выводе PHP 7.4 есть ошибка разбора, связанная с EnumClass::Case->value, ->name, прежним методом перечисления, вызванным как метод экземпляра, или именованным аргументом неразрешённого типа, значит исправление не сопоставило этот шаблон. Здесь также действует ограничение clone-with: сопоставление аргументов не является рекурсивным, поэтому переопределяющее значение с вложенными скобками не переписывается. Сверено с scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) и rector/rules/DowngradeCloneWithRector.php (документированное ограничение).

Этап: генерация composer.json

Этот этап перемещает обработанные каталоги src/ и tests/ из временного каталога сборки в выходной каталог. Затем он записывает сгенерированный composer.json. Сбой здесь почти всегда связан с состоянием файловой системы: выходной каталог недоступен для записи или временное дерево сборки отсутствует, потому что Rector ничего не создал. Сверено с scripts/build.php (adjustComposer(), moveTree()).

Этап: копирование статических ресурсов

Этот этап копирует LICENSE из основного исходного репозитория и записывает сгенерированный CHANGELOG.md. Если LICENSE отсутствует, копирование молча пропускается и сборка продолжается; журнал изменений записывается всегда. Сбой здесь означает, что выходной каталог стал недоступен для записи в середине сборки. Сверено с scripts/build.php (copyStaticAssets()).

Этап: проверка вывода

Ошибки «Output src/ directory not found» / «No PHP files found in output»

Для проверки требуется непустой output/src. Пустое дерево означает, что слияние ничего не скопировало или перемещение файлов завершилось сбоем. Сверено с scripts/build.php (validateOutput()).

Сообщение «Syntax validation: skipped (requires PHP runtime)»

Это ожидаемое поведение, а не ошибка. Хост сборки работает на современной версии PHP, а не в целевой среде выполнения, поэтому локальный этап только подсчитывает файлы и выводит команду Docker для настоящей проверки синтаксиса. Окончательным барьером проверки синтаксиса служит шаг php -l после сборки в рабочем процессе выпуска: он выполняется в фактической целевой среде выполнения. Сверено с scripts/build.php (validateOutput()) и .github/workflows/build.yml (шаги проверки синтаксиса PHP 8.1 / PHP 7.4).

Известные ограничения

Эти ограничения присущи самому подходу понижения версии. Они сверены с правилами и разделом “Known Limitations” файла README.md проекта:

Readonly-свойства удаляются. Сборка удаляет readonly, чтобы развёртывание clone-with могло явно присваивать свойства в более старой среде выполнения. В пониженном выводе больше нет неизменяемости, которую обеспечивает среда выполнения.
#[Override] не контролируется в PHP 8.1. Атрибут может сохраниться, но более старая среда выполнения на него не реагирует.
Целевая платформа PHP 7.4 включает только ядро. Адаптеры фреймворков, слой совместимости с tcpdf и Pro исключены из дистрибутива PHP 7.4 в силу устройства скрипта сборки.
Pro — это отдельный пакет только для PHP 8.1. Сборки Pro для PHP 7.4 не существует.
Сопоставление аргументов clone-with не является рекурсивным. Переопределяющие значения, содержащие вложенные скобки, не преобразуются, и только строковые ключи массива сопоставляются с именами свойств.

/integrations/backport/configuration/ — справочник по правилам и флагам.
/integrations/backport/production-usage/ — барьер CI и каналы выпуска.