Konfiguracja NextPDF Backport Builder

Narzędzia kompilacji — NIE zależność czasu wykonania. Wszystko na tej stronie dotyczy konfiguracji transformacji kodu źródłowego w czasie kompilacji. Nic z tego nie trafia do docelowego środowiska wykonawczego.

W skrócie

Transformacją sterują trzy pliki konfiguracyjne Rectora w katalogu rector/config/ oraz trzy niestandardowe reguły w katalogu rector/rules/. Wybór konfiguracji zależy od celu. Cel PHP 8.1 wykorzystuje jeden przebieg Rectora. Cel PHP 7.4 korzysta z dwuprzebiegowego potoku z etapem poprawek między przebiegami. Drugi przebieg jest wymagany, ponieważ Rector nie potrafi rozwiązać wartości domyślnych przypadków enum w jednym przejściu.

Konfiguracje Rectora

Plik	Przeznaczenie	Używany przez
rector/config/rector-php81.php	Jednoprzebiegowy downgrade do PHP 8.1	Cel PHP 8.1
rector/config/rector-php74-enums.php	Przebieg 1 — konwersja enumów na klasy z listą stałych	Cel PHP 7.4
rector/config/rector-php74.php	Przebieg 2 — pełny downgrade do PHP 7.4	Cel PHP 7.4

Każda konfiguracja wywołuje łańcuch zestawów downgrade Rectora (withDowngradeSets(php81: true) lub withDowngradeSets(php74: true)) dla elementów języka obsługiwanych natywnie przez Rectora. Następnie rejestruje niestandardowe reguły dla pozostałych elementów. Zweryfikowano względem trzech plików w katalogu rector/config/.

Reguły pomijania

rector-php81.php i rector-php74.php pomijają oba */tests/Benchmark/*. Skrypty benchmarków odwołują się do zewnętrznych bibliotek formatu Portable Document Format (PDF), których Rector nie potrafi rozwiązać, co powoduje awarię resolvera parametrów domyślnych. rector-php74.php pomija także DowngradeHashAlgorithmXxHashRector. Ta wbudowana reguła powoduje awarię na stałych MHASH_XXH* wycofanych ze współczesnego PHP, a kod źródłowy nie używa xxHash. Zweryfikowano względem wywołań withSkip() w obu plikach.

Trzy niestandardowe reguły

Repozytorium dostarcza dokładnie trzy niestandardowe reguły Rectora. Wszystkie trzy są zarejestrowane w pliku rector-php81.php; reguły asymetrycznej widoczności, clone-with oraz stałych w traitach są rejestrowane również w pliku rector-php74.php. tests/Rector/RectorRulesMetadataTest.php potwierdza to bezpośrednio: konstruuje każdą regułę oraz sprawdza jej definicję i typy węzłów.

DowngradeAsymmetricVisibilityRector

Usuwa modyfikator set asymetrycznej widoczności. Właściwość lub promowany parametr zadeklarowany jako public private(set) staje się zwykłym public. Dostęp do odczytu pozostaje zachowany; ograniczenie settera na etapie kompilacji zostaje usunięte. Gdy nie pozostaje żadna widoczność odczytu, reguła domyślnie przyjmuje public. Transformacja oparta na źródle z 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

Przepisuje formę funkcyjną clone() z tablicą nadpisań na klon, jawne przypisania właściwości oraz zwrot zmiennej tymczasowej. Licznik zmiennych tymczasowych resetuje się dla każdego pliku. Ta reguła musi działać po regule usuwającej właściwości readonly, ponieważ w przeciwnym razie rozwinięte przypisanie zakończyłoby się niepowodzeniem na właściwości readonly. Transformacja oparta na źródle z 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;
    }
}

Reguła ma udokumentowane ograniczenia. Dopasowanie argumentów używa wzorca nierekurencyjnego, więc wartości nadpisań z zagnieżdżonymi nawiasami nie są obsługiwane. Tylko klucze tablicy będące łańcuchami znaków są rozwiązywane do nazw właściwości. Zweryfikowano względem rector/rules/DowngradeCloneWithRector.php i jego zestawu fixture.

DowngradeTraitConstantsRector

Konwertuje stałe traitów na właściwości statyczne. Wcześniejsze środowiska wykonawcze odrzucają stałe traitów komunikatem “Traits cannot have constants”. Reguła przepisuje także odwołania self::CONST i static::CONST na formę właściwości statycznej. Widoczność zostaje zachowana; modyfikator final zostaje usunięty, ponieważ w starszym celu właściwości nie mogą być final. Typowana stała klasowa staje się typowaną właściwością. Transformacja oparta na źródle z 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;
    }
}

Dwuprzebiegowy potok PHP 7.4

Dla celu PHP 7.4 nie wystarcza jeden przebieg. Resolver wartości parametrów domyślnych Rectora ulega awarii na wartościach domyślnych przypadków enum w promowanych parametrach konstruktora. Skrypt kompilacji uruchamia więc:

1. Przebieg 1 — wstępne przetwarzanie enumów. rector-php74-enums.php uruchamia wyłącznie wbudowaną regułę konwersji enumów na klasy z listą stałych. Po tym przebiegu przypadki enum są zwykłymi stałymi klasowymi.
2. Czyszczenie pamięci podręcznej. Pamięć podręczna Rectora jest czyszczona, aby drugi przebieg nie widział nieaktualnego drzewa.
3. Poprawki po przetwarzaniu. scripts/build.php przepisuje wzorce, których reguła konwersji enumów na klasy nie obejmuje. Dawne metody instancyjne enumów stają się statyczne. Odwołania EnumClass::Case->value oraz ->name są rozwiązywane. Argumenty nazwane, których Rector nie mógł powiązać, są spłaszczane do argumentów pozycyjnych. Bez tych poprawek wzorce składniowe powodowałyby błędy parsowania na PHP 7.4.
4. Przebieg 2 — pełny downgrade. rector-php74.php uruchamia pełny łańcuch downgrade do PHP 7.4 wraz z niestandardowymi regułami.

Zweryfikowano względem scripts/build.php (runRector(), postProcessFixups()).

Wykaz flag kompilacji

scripts/build.php orkiestruje kompilację. Opcje zweryfikowano względem wywołania getopt() oraz konstruktora Build:

Flaga	Wartość domyślna	Działanie
--version=<x.y.z>	2.0.0	Wersja zapisywana w wygenerowanym pliku composer.json oraz CHANGELOG.md
--source-dir=<path>	c:/Users/admin/Documents	Katalog główny zawierający sąsiednie repozytoria źródłowe
--output-dir=<path>	<repo>/output	Miejsce zapisu wygenerowanej dystrybucji
--target=php74 | --target=php81	php81	Cel downgrade’u. php74 wymusza sam rdzeń i wyłącza Pro
--dry-run	wyłączone	Uruchamia każdy etap w trybie tylko raportowania; kopiowanie i Rector są pomijane
--no-pro	wyłączone	Wyklucza pakiet Pro (tylko cel PHP 8.1; PHP 7.4 już go wyklucza)

Nieprawidłowa wartość --target zgłasza InvalidArgumentException przed rozpoczęciem jakiejkolwiek pracy. Zweryfikowano względem Build::__construct() (zabezpieczenie VALID_TARGETS).

Skrypty Composera

Skrypt	Polecenie	Przeznaczenie
composer test	phpunit	Uruchamia zestawy fixture dla reguł
composer analyse	phpstan analyse rector/rules scripts --level=10	Analiza statyczna kodu kompilacji
composer build	php scripts/build.php	Pełna kompilacja
composer build:dry	php scripts/build.php --dry-run	Kompilacja w trybie dry-run

Zweryfikowano względem composer.jsonscripts.

Dalej

• /integrations/backport/quickstart/ — uruchom tryb dry-run i pełną kompilację.
• /integrations/backport/troubleshooting/ — co oznacza awaria na każdym etapie.