Справочник API Backport Builder

Кратко

Backport Builder — это инструмент сборки, а не библиотека времени выполнения. Его публичный интерфейс состоит из набора команд сборки (scripts/build.php и его обёрток composer build*), четырёх классов уровня скриптов, которые их обслуживают (Build, MergeSources, AdjustComposer, ValidateBuildContract), трёх файлов конфигурации Rector, трёх пользовательских правил Rector и контракта генерируемого пакета (nextpdf/backport и nextpdf/backport-pro). Запускайте его на узле сборки или в среде непрерывной интеграции (CI), чтобы преобразовать современный исходный код NextPDF в backport-дистрибутив. Никогда не добавляйте его в приложение.

Если вы только начинаете, запустите composer build:dry (эта команда раскрывается в php scripts/build.php --dry-run). Она прогоняет каждый этап в режиме “только отчёт”, не записывая файлы, поэтому вы можете проверить структуру исходного кода и флаги перед настоящей сборкой. В первом примере раздела “Типовые задачи” показана та же команда.

Типовые задачи

Чаще всего этот пакет используют для запуска сборок на узле сборки. Каждый приведённый ниже пример — одна команда, проверенная по scripts/build.php и composer.json.

Проверьте конвейер, ничего не записывая (безопасный первый запуск):

composer build:dry

Команда раскрывается в php scripts/build.php --dry-run. Она выполняет слияние, Rector, генерацию composer, копирование ресурсов и проверку в режиме “только отчёт”, ничего не копируя.

Создайте полный дистрибутив для PHP 8.1 (nextpdf/backport, а также nextpdf/backport-pro, когда присутствует исходный код Pro):

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

Команда объединяет ядро, адаптеры фреймворков и слой совместимости с tcpdf. Она выполняет один проход Rector для цели PHP 8.1 и записывает дерево генерируемого пакета в ./output. Добавьте --no-pro, чтобы пропустить пакет Pro.

Создайте дистрибутив только с ядром для PHP 7.4 (двухпроходный конвейер для enum):

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

--target=php74 принудительно создаёт вывод только с ядром, отключает Pro и выполняет предобработку enum, исправления после Rector и полный проход понижения версии до PHP 7.4.

Командные интерфейсы

Используйте эту таблицу, когда нужны точные сигнатуры, флаги и поведение при завершении для точек входа сборки и классов уровня скриптов, которые управляют сборкой.

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения или завершение с ошибкой	Примечания
scripts/build.php	Цель, версия, пути к исходному коду, пути вывода и флаги, как описано в скрипте.	Использует значения цели по умолчанию для конкретной ветки.	Дерево генерируемого пакета.	Ненулевой код завершения и сообщения об ошибках конкретного этапа.	Основная точка входа сборки. Запускайте на узле сборки, а не в приложении.
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)	Версия, каталог исходного кода, каталог вывода, целевая линия среды выполнения, флаг включения Pro, флаг пробного запуска.	Нацеливается на PHP 8.1, включает Pro для целей, кроме PHP 7.4, и записывает файлы, если не включён пробный запуск.	Build	InvalidArgumentException для неподдерживаемой цели; ошибки этапов во время run().	Класс уровня скрипта, стоящий за scripts/build.php.
Build::run()	Нет.	Проверяет контракт, объединяет исходный код, корректирует метаданные composer.json и выполняет проходы Rector.	bool	Возвращает false при ожидаемых сбоях этапов; может выбрасывать исключение при непредвиденных ошибках файловой системы или времени выполнения.	CI должен завершаться с ошибкой при false.
composer build:dry	Обёртка для Composer-скрипта.	Проверка сборки в пробном запуске.	Код завершения и журналы.	Ненулевой код завершения при сбое сборки или проверки.	Используется шлюзами CI.
scripts/merge-sources.php	Пути к извлечённому исходному коду и цель слияния.	Объединяет выбранные исходные пакеты для целевой среды выполнения.	Объединённое дерево исходного кода.	Отсутствующий исходный код, неподдерживаемая цель, сбой файловой системы.	Следите, чтобы ссылки на исходный код соответствовали тегу выпуска.
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)	Базовый каталог исходного кода, каталог вывода, флаг включения Pro, флаг пробного запуска, флаг “только ядро”.	Объединяет все настроенные репозитории или только ядро, если coreOnly равно true.	MergeSources	Недопустимые пути к исходному коду или выводу во время выполнения.	Класс уровня скрипта, стоящий за scripts/merge-sources.php.
MergeSources::run()	Нет.	Копирует и нормализует выбранные деревья исходного кода в цель сборки.	bool	Возвращает false при ожидаемых сбоях слияния.	Журналы можно прочитать с помощью getLog().
MergeSources::getLog()	Нет.	Возвращает накопленные записи журнала этапов.	array	Не ожидается.	Используйте для диагностики CI.
scripts/adjust-composer.php	Метаданные и версия генерируемого composer.json.	Записывает ограничения пакетов и записи replace для генерируемого вывода.	Скорректированный composer.json.	Недопустимая версия или отсутствующие генерируемые файлы.	Определяет идентичность генерируемого пакета.
AdjustComposer::__construct(string $version, string $target = 'php81')	Строка версии и целевая линия.	Цель PHP 8.1.	AdjustComposer	Ошибки из-за недопустимой цели в путях генерации.	Используется скриптами сборки и тестами.
AdjustComposer::generatePublicComposer()	Нет.	Создаёт метаданные для nextpdf/backport.	array	Не ожидается.	Чистый API генерации для тестов.
AdjustComposer::generateProComposer()	Нет.	Создаёт метаданные для nextpdf/backport-pro.	array	Не ожидается.	Чистый API генерации для проприетарной линии сборки.
AdjustComposer::writePublicComposer(string $outputDir)	Каталог вывода.	Записывает генерируемый публичный composer.json.	void	Ошибки файловой системы.	Используйте только в каталогах генерируемого вывода.
AdjustComposer::writeProComposer(string $proOutputDir)	Каталог вывода Pro.	Записывает генерируемый composer.json для Pro.	void	Ошибки файловой системы.	Требует, чтобы дерево вывода Pro существовало.
ValidateBuildContract::__construct(string $repoRoot)	Корень репозитория.	Использует предоставленный корень репозитория в качестве базы контракта.	ValidateBuildContract	Не ожидается.	Валидатор контракта уровня скрипта.
ValidateBuildContract::run()	Нет.	Проверяет необходимые входные данные и предположения сборки.	bool	Возвращает false при сбое контракта.	Запускайте до того, как вывод сборки будет признан надёжным.

Конфигурация Rector

Используйте эту таблицу, чтобы понять, какой файл конфигурации Rector управляет каждой целевой линией и как каждый проход встроен в однопроходный конвейер PHP 8.1 или двухпроходный конвейер PHP 7.4.

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения или завершение с ошибкой	Примечания
rector/config/rector-php81.php	Дерево исходного кода и среда выполнения Rector.	Однопроходное понижение версии до цели PHP 8.1.	Преобразованный исходный код.	Сбой разбора или преобразования Rector.	Используется для линии дистрибутива PHP 8.1.
rector/config/rector-php74-enums.php	Дерево исходного кода и среда выполнения Rector.	Первый проход PHP 7.4 для преобразования enum.	Промежуточный преобразованный исходный код.	Сбой разбора или преобразования Rector.	Выполняется перед полным проходом PHP 7.4.
rector/config/rector-php74.php	Промежуточный исходный код и среда выполнения Rector.	Полный проход понижения версии до PHP 7.4.	Исходный код, совместимый с PHP 7.4.	Сбой разбора или преобразования Rector.	Используется для линии дистрибутива PHP 7.4.

Пользовательские правила

Используйте эту таблицу, когда сопровождаете или расширяете три проектно-специфичных правила Rector и вам нужен контракт методов каждого правила, а также синтаксис, который оно преобразует.

Символ	Параметры	Поведение по умолчанию	Возвращает	Исключения или завершение с ошибкой	Примечания
DowngradeAsymmetricVisibilityRector	Свойства или продвигаемые параметры, использующие асимметричную видимость.	Обычная видимость, совместимая со старыми средами выполнения.	Сохраняет видимость для чтения, где это возможно.	Сбой правила Rector.	Ограничения сеттера действуют только во время компиляции и удаляются в генерируемом выводе.
DowngradeAsymmetricVisibilityRector::getRuleDefinition()	Нет.	Возвращает метаданные правила Rector и примеры.	RuleDefinition	Не ожидается.	Оставляет документацию правила видимой для инструментов Rector.
DowngradeAsymmetricVisibilityRector::getNodeTypes()	Нет.	Выбирает типы узлов, проверяемых правилом.	array<class-string<Node>>	Не ожидается.	Область действия должна оставаться узкой для детерминированных преобразований.
DowngradeAsymmetricVisibilityRector::refactor(Node $node)	Узел AST.	Преобразует асимметричную видимость там, где она присутствует.	`Node	null`	Сбой правила Rector.
DowngradeCloneWithRector	clone() с переопределениями свойств.	Клонирование плюс явные присваивания свойств.	Использует генерируемые временные переменные.	Сбой правила Rector.	Должен выполняться после понижения версии readonly-свойств.
DowngradeCloneWithRector::getRuleDefinition()	Нет.	Возвращает метаданные правила и примеры.	RuleDefinition	Не ожидается.	Используется диагностикой Rector.
DowngradeCloneWithRector::getNodeTypes()	Нет.	Выбирает узлы return и выражения.	array<class-string<Node>>	Не ожидается.	Сохраняет фокус правила на синтаксисе clone-with.
DowngradeCloneWithRector::refactor(Node $node)	Узел AST.	Переписывает clone-with в клонирование плюс присваивания.	`array	null`	Сбой правила Rector.
DowngradeTraitConstantsRector	Константы трейтов и ссылки на них.	Статические свойства и ссылки на свойства.	Сохраняет видимость, где это возможно.	Сбой правила Rector.	Удаляет final, поскольку более старые свойства не могут быть final.
DowngradeTraitConstantsRector::getRuleDefinition()	Нет.	Возвращает метаданные правила и примеры.	RuleDefinition	Не ожидается.	Используется диагностикой Rector.
DowngradeTraitConstantsRector::getNodeTypes()	Нет.	Выбирает узлы трейтов и обращений к константам класса.	array<class-string<Node>>	Не ожидается.	Ограничивает правило константами трейтов.
DowngradeTraitConstantsRector::refactor(Node $node)	Узел AST.	Переписывает константы трейтов и ссылки на них в совместимые свойства.	`Node	null`	Сбой правила Rector.

Контракт генерируемого пакета

Используйте эту таблицу, чтобы понять, что создаёт сборщик: имена пакетов, которые устанавливают потребляющие проекты, и пакет, содержащий дистрибутив Pro.

Выпускаемый пакет	Роль во время выполнения	Примечания
nextpdf/backport	Генерируемый дистрибутив среды выполнения с открытым исходным кодом.	Заменяет выбранные пакеты nextpdf/* для целевой среды выполнения.
nextpdf/backport-pro	Генерируемый проприетарный дистрибутив Pro, если присутствует исходный код Pro.	Публикуется отдельно от пакета с открытым исходным кодом.

Заметки по разработке

• Сборщик принимает выпуски исходного кода и создаёт генерируемые артефакты. Не правьте генерируемый вывод как источник истины.
• Каждое пользовательское правило должно иметь fixture-тесты, прежде чем оно попадёт в конвейер сборки.
• Задания выпуска должны проверять генерируемый вывод в целевой среде выполнения, а не только на узле сборки.