Настройка NextPDF Backport Builder

Инструментарий сборки — это НЕ зависимость времени выполнения. Всё на этой странице относится к преобразованию исходного кода во время сборки. Ничто из этого не попадает в целевую среду выполнения.

Кратко

Преобразование задают три файла конфигурации Rector в каталоге rector/config/ и три пользовательских правила в каталоге rector/rules/. Выбор конфигурации зависит от целевой версии. Для цели PHP 8.1 используется один проход Rector. Для цели PHP 7.4 используется двухпроходный конвейер с этапом корректировок между проходами. Второй проход нужен, потому что Rector не может за один обход разрешить значения по умолчанию для вариантов перечисления.

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

Файл	Назначение	Используется
rector/config/rector-php81.php	Понижение версии до PHP 8.1 за один проход	Цель PHP 8.1
rector/config/rector-php74-enums.php	Проход 1 — преобразование перечислений в классы со списком констант	Цель PHP 7.4
rector/config/rector-php74.php	Проход 2 — полное понижение версии до PHP 7.4	Цель PHP 7.4

Каждая конфигурация вызывает цепочку наборов понижения версии Rector (withDowngradeSets(php81: true) или withDowngradeSets(php74: true)) для возможностей, которые Rector поддерживает штатно. Затем она регистрирует пользовательские правила для оставшихся возможностей. Проверено по трём файлам в rector/config/.

Правила пропуска

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

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

Репозиторий поставляет ровно три пользовательских правила Rector. Все три зарегистрированы в rector-php81.php; правила для асимметричной видимости, clone-with и констант трейтов также зарегистрированы в rector-php74.php. tests/Rector/RectorRulesMetadataTest.php проверяет это напрямую: создаёт каждое правило и сверяет его определение и типы узлов.

DowngradeAsymmetricVisibilityRector

Удаляет модификатор set асимметричной видимости. Свойство или продвинутый параметр, объявленный как public private(set), становится обычным public. Доступ на чтение сохраняется; ограничение сеттера на этапе компиляции снимается. Если видимость на чтение не остаётся, правило по умолчанию использует public. Преобразование подтверждено исходным кодом из tests/Rector/Fixtures/DowngradeAsymmetricVisibility/public_private_set.php.inc:

before

<?php

class Config {
    public private(set) float $x = 0.0;
    public private(set) string $name = '';
    public private(set) int $count = 0;
}

after

<?php

class Config {
    public float $x = 0.0;
    public string $name = '';
    public int $count = 0;
}

DowngradeCloneWithRector

Переписывает функциональную форму clone() с массивом переопределений в клонирование, явные присваивания свойств и возврат временной переменной. Счётчик временных переменных сбрасывается для каждого файла. Это правило должно выполняться после правила удаления readonly-свойств, иначе развёрнутое присваивание завершится сбоем на readonly-свойстве. Преобразование подтверждено исходным кодом из tests/Rector/Fixtures/DowngradeCloneWith/return_clone_with.php.inc:

before

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self {
        return clone($this, ['width' => $width, 'height' => $height]);
    }
}

after

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self
    {
        $__cloneResult1 = clone $this;
        $__cloneResult1->width = $width;
        $__cloneResult1->height = $height;
        return $__cloneResult1;
    }
}

У этого правила есть задокументированные ограничения. Сопоставление аргументов использует нерекурсивный шаблон, поэтому значения переопределений с вложенными скобками не обрабатываются. В качестве имён свойств допускаются только строковые ключи массива. Проверено по rector/rules/DowngradeCloneWithRector.php и его набору фикстур.

DowngradeTraitConstantsRector

Преобразует константы трейтов в статические свойства. Более ранние среды выполнения отклоняют константы трейтов с сообщением “Traits cannot have constants”. Правило также переписывает ссылки self::CONST и static::CONST в форму статического свойства. Видимость сохраняется; модификатор final удаляется, потому что в более старой целевой версии свойства не могут быть final. Типизированная константа класса становится типизированным свойством. Преобразование подтверждено исходным кодом из tests/Rector/Fixtures/DowngradeTraitConstants/private_constant.php.inc:

before

<?php

trait HasLimit
{
    private const MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::MAX_SIZE;
    }
}

after

<?php

trait HasLimit
{
    private static $MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::$MAX_SIZE;
    }
}

Двухпроходный конвейер PHP 7.4

Цель PHP 7.4 нельзя обработать за один проход. Сопоставитель значений параметров по умолчанию Rector завершается сбоем на значениях по умолчанию для вариантов перечисления в продвижении параметров конструктора. Поэтому скрипт сборки выполняет:

1. Проход 1 — предобработка перечислений. rector-php74-enums.php выполняет только встроенное правило преобразования перечисления в класс со списком констант. После этого прохода варианты перечисления становятся обычными константами класса.
2. Очистка кэша. Кэш Rector очищается, чтобы второй проход не видел устаревшее дерево.
3. Корректировки на этапе постобработки. scripts/build.php переписывает шаблоны, которые не охватывает правило преобразования перечисления в класс. Прежние методы экземпляра перечисления становятся статическими. Обращения EnumClass::Case->value и ->name разрешаются. Именованные аргументы, которые Rector не смог привязать, преобразуются в позиционные. Без этого такие синтаксические шаблоны вызвали бы ошибки разбора в PHP 7.4.
4. Проход 2 — полное понижение версии. rector-php74.php выполняет полную цепочку понижения версии PHP 7.4 плюс пользовательские правила.

Проверено по scripts/build.php (runRector(), postProcessFixups()).

Справочник по флагам сборки

scripts/build.php управляет сборкой. Его параметры проверены по вызову getopt() и конструктору Build:

Флаг	По умолчанию	Действие
--version=<x.y.z>	2.0.0	Версия, записываемая в сгенерированные composer.json и CHANGELOG.md
--source-dir=<path>	c:/Users/admin/Documents	Корневой каталог с соседними репозиториями исходного кода
--output-dir=<path>	<repo>/output	Куда записывается сгенерированный дистрибутив
--target=php74 | --target=php81	php81	Целевая версия понижения. php74 принудительно включает только core и отключает Pro
--dry-run	выкл.	Запускает каждый этап в режиме только отчёта; копирование и Rector пропускаются
--no-pro	выкл.	Исключает пакет Pro (только для цели PHP 8.1; PHP 7.4 уже исключает его)

Недопустимое значение --target вызывает InvalidArgumentException до начала любой работы. Проверено по Build::__construct() (проверка VALID_TARGETS).

Скрипты Composer

Скрипт	Команда	Назначение
composer test	phpunit	Запускает наборы фикстур для правил
composer analyse	phpstan analyse rector/rules scripts --level=10	Выполняет статический анализ кода сборки
composer build	php scripts/build.php	Полная сборка
composer build:dry	php scripts/build.php --dry-run	Пробная сборка

Проверено по composer.jsonscripts.

Далее

• /integrations/backport/quickstart/ — запуск пробной и полной сборки.
• /integrations/backport/troubleshooting/ — значения этапов сбоя.