Rozwiązywanie problemów w NextPDF Backport Builder

To są narzędzia kompilacji — NIE zależność uruchomieniowa. Każdy objaw opisany na tej stronie dotyczy stanu występującego podczas kompilacji na hoście opiekuna projektu lub na hoście ciągłej integracji (CI). Żaden z tych stanów nie występuje w aplikacji końcowej.

W skrócie

Kompilacja przebiega przez pięć uporządkowanych etapów. Zatrzymuje się przy pierwszym błędzie, wypisując nazwę etapu oraz komunikat. Odczytaj nazwę etapu, a następnie znajdź poniżej odpowiadającą jej przyczynę. Etapy to: scalanie źródeł, obniżanie wersji narzędziem Rector, wygenerowanie composer.json, skopiowanie zasobów statycznych oraz walidacja danych wyjściowych. Zweryfikowano względem scripts/build.php (run() oraz step()).

Etap: scalanie źródeł

„Source repo '' not found at: ”

Przed skopiowaniem plików etap scalania sprawdza każde oczekiwane repozytorium źródłowe. Jeśli repozytorium jest niedostępne, kompilacja zostaje przerwana, a jego nazwa i ścieżka są wypisywane. Cel PHP 8.1 oczekuje nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter oraz — gdy dołączona jest wersja Pro — nextpdf-Pro. Cel PHP 7.4 oczekuje wyłącznie nextpdf. Zweryfikowano względem scripts/merge-sources.php (pętla walidacji run(), mapa repozytoriów __construct()).

Rozwiązanie: pobierz repozytoria jako katalogi równorzędne względem ścieżki przekazanej do --source-dir i użyj dokładnie nazw katalogów podanych powyżej. Przebieg próbny wypisuje każde repozytorium, które zostałoby odczytane. Użyj go, aby potwierdzić układ przed uruchomieniem pełnej kompilacji.

Etap: obniżanie wersji narzędziem Rector

Rector kończy działanie z kodem różnym od zera

Orkiestrator zgłasza Rector failed on <label> (exit code: N) i zatrzymuje pracę. Etykieta wskazuje przebieg, który zakończył się niepowodzeniem: public package, pro package, enum pre-processing lub full downgrade. Zweryfikowano względem scripts/build.php (runRectorPass()).

Awaria mechanizmu rozwiązywania parametrów domyślnych przy domyślnych wartościach typu enum (PHP 7.4)

Właśnie dlatego cel PHP 7.4 korzysta z dwóch przebiegów. Mechanizm rozwiązywania domyślnych wartości parametrów w narzędziu Rector ulega awarii, gdy przypadek typu enum zostanie użyty jako wartość domyślna w promocji konstruktora. Przebieg 1 (rector-php74-enums.php) najpierw przekształca typy enum w klasy z listą stałych. Dzięki temu pełny przebieg w przebiegu 2 nigdy nie napotyka domyślnej wartości w postaci przypadku typu enum. Jeśli pominiesz orkiestrator i uruchomisz pełną konfigurację PHP 7.4 bezpośrednio na źródle zawierającym typy enum, spodziewaj się tej awarii. Zweryfikowano względem scripts/build.php (komentarz runRector() oraz sekwencja dwuprzebiegowa) i rector/config/rector-php74-enums.php.

Skrypty testów wydajnościowych powodują awarię narzędzia Rector

rector-php81.php i rector-php74.php pomijają */tests/Benchmark/*. Skrypty te odwołują się do zewnętrznych bibliotek obsługujących format Portable Document Format (PDF), których Rector nie potrafi rozwiązać, co powoduje awarię mechanizmu rozwiązywania parametrów domyślnych. Jeśli ścieżka testu wydajnościowego jest przetwarzana, oznacza to, że brakuje wzorca pominięcia lub ścieżka się różni. Zweryfikowano względem wywołań withSkip().

MHASH_XXH* — awaria (PHP 7.4)

rector-php74.php pomija DowngradeHashAlgorithmXxHashRector. Ta wbudowana reguła ulega awarii przy stałych xxHash. Źródło nie korzysta z xxHash, więc takie pominięcie jest bezpieczne. Zweryfikowano względem rector/config/rector-php74.php (withSkip()).

Etap: poprawki po Rectorze (tylko PHP 7.4)

Poprawki są wykonywane między dwoma przebiegami. Przepisują wzorce pozostawione przez regułę przekształcającą enum w klasę. Jeśli dane wyjściowe PHP 7.4 zawierają błąd parsowania związany z EnumClass::Case->value, ->name, dawną metodą typu enum wywoływaną jako metoda instancji lub argumentem nazwanym dla nierozwiązanego typu, oznacza to, że poprawka nie dopasowała danego wzorca. Tutaj również obowiązuje ograniczenie clone-with: dopasowywanie argumentów nie jest rekurencyjne, więc wartość nadpisująca z zagnieżdżonymi nawiasami nie zostanie przepisana. Zweryfikowano względem scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) i rector/rules/DowngradeCloneWithRector.php (udokumentowane ograniczenie).

Etap: generowanie composer.json

Ten etap przenosi przetworzone katalogi src/ i tests/ z katalogu tymczasowego kompilacji do katalogu wyjściowego. Następnie zapisuje wygenerowany composer.json. Błąd na tym etapie niemal zawsze wynika ze stanu systemu plików: katalog wyjściowy nie jest zapisywalny lub brakuje drzewa tymczasowego kompilacji, ponieważ Rector niczego nie wytworzył. Zweryfikowano względem scripts/build.php (adjustComposer(), moveTree()).

Etap: kopiowanie zasobów statycznych

Ten etap kopiuje plik LICENSE z głównego repozytorium źródłowego i zapisuje wygenerowany plik CHANGELOG.md. Jeśli plik LICENSE jest nieobecny, kopiowanie zostaje pominięte bez komunikatu, a kompilacja jest kontynuowana; dziennik zmian zapisywany jest zawsze. Błąd na tym etapie oznacza, że katalog wyjściowy stał się niezapisywalny w trakcie kompilacji. Zweryfikowano względem scripts/build.php (copyStaticAssets()).

Etap: walidacja danych wyjściowych

Komunikaty „Output src/ directory not found” oraz „No PHP files found in output”

Walidacja wymaga niepustego output/src. Puste drzewo oznacza, że etap scalania niczego nie skopiował albo przeniesienie plików zakończyło się niepowodzeniem. Zweryfikowano względem scripts/build.php (validateOutput()).

„Syntax validation: skipped (requires PHP runtime)”

To oczekiwane zachowanie, a nie błąd. Host kompilacji uruchamia nowoczesną wersję PHP, a nie docelowe środowisko uruchomieniowe, więc lokalny etap jedynie zlicza pliki i wypisuje polecenie Docker do rzeczywistego sprawdzenia składni. Miarodajną bramką sprawdzania składni jest powykompilacyjny krok php -l w przepływie pracy wydania, który działa w rzeczywistym docelowym środowisku uruchomieniowym. Zweryfikowano względem scripts/build.php (validateOutput()) i .github/workflows/build.yml (kroki sprawdzania składni PHP 8.1 / PHP 7.4).

Znane ograniczenia

Ograniczenia te są nieodłączną cechą podejścia opartego na obniżaniu wersji. Zweryfikowano je względem reguł oraz sekcji „Known Limitations” w pliku README.md projektu:

• Właściwości readonly są usuwane. Kompilacja usuwa readonly, aby rozwinięcie clone-with mogło jawnie przypisywać właściwości w starszym środowisku uruchomieniowym. Dane wyjściowe po obniżeniu wersji nie mają już niezmienności wymuszanej w czasie wykonywania.
• #[Override] nie jest wymuszane w PHP 8.1. Atrybut może pozostać, lecz starsze środowisko uruchomieniowe go nie uwzględnia.
• Cel PHP 7.4 obejmuje wyłącznie rdzeń. Adaptery frameworków, warstwa zgodności z tcpdf oraz wersja Pro są z założenia wykluczone z dystrybucji PHP 7.4 ze względu na sposób działania skryptu kompilacji.
• Pro to osobny pakiet dostępny tylko dla PHP 8.1. Nie istnieje kompilacja Pro dla PHP 7.4.
• Dopasowywanie argumentów clone-with nie jest rekurencyjne. Wartości nadpisujące zawierające zagnieżdżone nawiasy nie są przekształcane, a na nazwy właściwości mapowane są tylko łańcuchowe klucze tablicy.

Dalsze kroki

• /integrations/backport/configuration/ — omówienie reguł i flag.
• /integrations/backport/production-usage/ — bramka CI i ścieżki wydań.