Dokumentacja API narzędzia Backport Builder

W skrócie

Backport Builder jest narzędziem kompilacji, a nie biblioteką uruchomieniową. Jego publiczny interfejs obejmuje zestaw poleceń kompilacji (scripts/build.php oraz jego otoki composer build*), cztery klasy na poziomie skryptów, na których się opiera (Build, MergeSources, AdjustComposer, ValidateBuildContract), trzy pliki konfiguracji Rectora, trzy niestandardowe reguły Rectora oraz kontrakt wygenerowanego pakietu (nextpdf/backport oraz nextpdf/backport-pro). Uruchamiaj ten zestaw na hoście kompilacji lub w środowisku ciągłej integracji (CI), aby przekształcić nowoczesny kod źródłowy NextPDF w dystrybucję przeznaczoną dla starszych wersji. Nigdy nie dodawaj tego narzędzia do aplikacji.

Na początek uruchom composer build:dry (które rozwija się do php scripts/build.php --dry-run). Polecenie wykonuje każdy etap wyłącznie w trybie raportowania, bez zapisywania plików, dzięki czemu można potwierdzić układ źródeł i flagi przed właściwą kompilacją. Pierwszy przykład w sekcji „Typowe zadania” pokazuje to samo polecenie.

Typowe zadania

Tego pakietu używa się najczęściej do uruchamiania kompilacji na hoście kompilacji. Każdy z poniższych przykładów to pojedyncze polecenie, zweryfikowane względem scripts/build.php oraz composer.json.

Sprawdź potok bez zapisywania czegokolwiek (bezpieczne pierwsze uruchomienie):

composer build:dry

Rozwija się do php scripts/build.php --dry-run. Uruchamia scalanie, Rectora, generowanie danych Composera, kopiowanie zasobów oraz walidację wyłącznie w trybie raportowania i niczego nie kopiuje.

Utwórz pełną dystrybucję PHP 8.1 (nextpdf/backport oraz nextpdf/backport-pro, gdy obecne są źródła Pro):

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

Scala rdzeń, adaptery frameworków oraz warstwę zgodności z tcpdf. Uruchamia pojedynczy przebieg Rectora dla celu PHP 8.1 i zapisuje wygenerowane drzewo pakietu w ./output. Dodaj --no-pro, aby pominąć pakiet Pro.

Utwórz dystrybucję PHP 7.4 zawierającą wyłącznie rdzeń (dwuprzebiegowy potok wyliczeń):

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

--target=php74 wymusza wynik zawierający wyłącznie rdzeń, wyłącza Pro oraz uruchamia wstępne przetwarzanie wyliczeń, poprawki po Rectorze i pełny przebieg obniżający do PHP 7.4.

Interfejsy poleceń

Skorzystaj z tej tabeli, gdy potrzebujesz dokładnych sygnatur, flag i zachowania przy zakończeniu dla punktów wejścia kompilacji oraz klas na poziomie skryptów sterujących kompilacją.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
scripts/build.php	Docelowa wersja PHP, wersja, ścieżki źródłowe, ścieżki wyjściowe oraz flagi zgodnie z dokumentacją skryptu.	Stosuje wartości domyślne właściwe dla gałęzi.	Wygenerowane drzewo pakietu.	Niezerowy kod wyjścia oraz komunikaty błędów właściwe dla danego etapu.	Główny punkt wejścia kompilacji. Uruchamiaj na hoście kompilacji, a nie w aplikacji.
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)	Wersja, katalog źródłowy, katalog wyjściowy, docelowe środowisko uruchomieniowe, flaga dołączenia Pro, flaga przebiegu próbnego.	Domyślnie celem jest PHP 8.1, Pro jest dołączane z wyjątkiem PHP 7.4, a zapis jest wykonywany, chyba że włączono przebieg próbny.	Build	InvalidArgumentException dla nieobsługiwanego celu; błędy etapów podczas run().	Klasa na poziomie skryptu stojąca za scripts/build.php.
Build::run()	brak.	Waliduje kontrakt, scala źródła, dostosowuje metadane composer.json oraz uruchamia przebiegi Rectora.	bool	Zwraca false dla oczekiwanych niepowodzeń etapów; może zgłosić wyjątek przy nieoczekiwanych błędach systemu plików lub środowiska uruchomieniowego.	CI powinno zakończyć zadanie niepowodzeniem przy false.
composer build:dry	Otoka skryptu Composera.	Waliduje kompilację w trybie próbnym.	Kod wyjścia i dzienniki.	Niezerowy kod wyjścia w razie niepowodzenia kompilacji lub walidacji.	Wykorzystywane przez bramki CI.
scripts/merge-sources.php	Ścieżki do pobranych źródeł oraz cel scalania.	Scala wybrane pakiety źródłowe dla docelowego środowiska uruchomieniowego.	Scalone drzewo źródłowe.	Brakujące źródło, nieobsługiwany cel, błąd systemu plików.	Utrzymuj odwołania do źródeł w zgodności z tagiem wydania.
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)	Bazowy katalog źródłowy, katalog wyjściowy, flaga dołączenia Pro, flaga przebiegu próbnego, flaga tylko dla rdzenia.	Scala wszystkie skonfigurowane repozytoria lub tylko rdzeń, gdy coreOnly ma wartość true.	MergeSources	Nieprawidłowe ścieżki źródłowe lub wyjściowe podczas uruchomienia.	Klasa na poziomie skryptu stojąca za scripts/merge-sources.php.
MergeSources::run()	brak.	Kopiuje i normalizuje wybrane drzewa źródłowe w celu kompilacji.	bool	Zwraca false dla oczekiwanych niepowodzeń scalania.	Dzienniki można odczytać za pomocą getLog().
MergeSources::getLog()	brak.	Zwraca zgromadzone wpisy dziennika etapów.	array	brak oczekiwanych.	Używaj do diagnostyki CI.
scripts/adjust-composer.php	Metadane i wersja wygenerowanego composer.json.	Zapisuje ograniczenia pakietów oraz wpisy zastąpień dla wygenerowanego wyniku.	Dostosowany composer.json.	Nieprawidłowa wersja lub brakujące wygenerowane pliki.	Odpowiada za tożsamość wygenerowanego pakietu.
AdjustComposer::__construct(string $version, string $target = 'php81')	Ciąg wersji oraz cel.	Cel PHP 8.1.	AdjustComposer	Błędy spowodowane nieprawidłowym celem w ścieżkach generowania.	Wykorzystywane przez skrypty kompilacji i testy.
AdjustComposer::generatePublicComposer()	brak.	Tworzy metadane dla nextpdf/backport.	array	brak oczekiwanych.	Czyste API generowania na potrzeby testów.
AdjustComposer::generateProComposer()	brak.	Tworzy metadane dla nextpdf/backport-pro.	array	brak oczekiwanych.	Czyste API generowania dla zastrzeżonej ścieżki kompilacji.
AdjustComposer::writePublicComposer(string $outputDir)	Katalog wyjściowy.	Zapisuje wygenerowany publiczny composer.json.	void	Błędy systemu plików.	Używaj wyłącznie w wygenerowanych katalogach wyjściowych.
AdjustComposer::writeProComposer(string $proOutputDir)	Katalog wyjściowy Pro.	Zapisuje wygenerowany composer.json Pro.	void	Błędy systemu plików.	Wymaga istnienia drzewa wyjściowego Pro.
ValidateBuildContract::__construct(string $repoRoot)	Katalog główny repozytorium.	Przyjmuje podany katalog główny repozytorium jako podstawę kontraktu.	ValidateBuildContract	brak oczekiwanych.	Walidator kontraktu na poziomie skryptu.
ValidateBuildContract::run()	brak.	Sprawdza wymagane dane wejściowe oraz założenia kompilacji.	bool	Zwraca false w razie niepowodzenia kontraktu.	Uruchamiaj, zanim zaufasz wynikowi kompilacji.

Konfiguracja Rectora

Skorzystaj z tej tabeli, aby zobaczyć, który plik konfiguracji Rectora steruje daną ścieżką docelową oraz gdzie każdy przebieg znajduje się w jednoprzebiegowym potoku PHP 8.1 albo dwuprzebiegowym potoku PHP 7.4.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
rector/config/rector-php81.php	Drzewo źródłowe oraz środowisko uruchomieniowe Rectora.	Jednoprzebiegowe obniżenie do PHP 8.1.	Przekształcony kod źródłowy.	Niepowodzenie parsowania lub przekształcania przez Rectora.	Używane dla ścieżki dystrybucji PHP 8.1.
rector/config/rector-php74-enums.php	Drzewo źródłowe oraz środowisko uruchomieniowe Rectora.	Pierwszy przebieg PHP 7.4 służący konwersji wyliczeń.	Pośredni przekształcony kod źródłowy.	Niepowodzenie parsowania lub przekształcania przez Rectora.	Uruchamiany przed pełnym przebiegiem PHP 7.4.
rector/config/rector-php74.php	Pośredni kod źródłowy oraz środowisko uruchomieniowe Rectora.	Pełny przebieg obniżania do PHP 7.4.	Kod źródłowy zgodny z PHP 7.4.	Niepowodzenie parsowania lub przekształcania przez Rectora.	Używane dla ścieżki dystrybucji PHP 7.4.

Reguły niestandardowe

Skorzystaj z tej tabeli, gdy utrzymujesz lub rozszerzasz trzy reguły Rectora specyficzne dla projektu i potrzebujesz kontraktu metod każdej reguły oraz składni, którą przekształca.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
DowngradeAsymmetricVisibilityRector	Właściwości lub promowane parametry korzystające z widoczności asymetrycznej.	Standardowa widoczność zgodna ze starszymi środowiskami uruchomieniowymi.	Zachowuje widoczność odczytu tam, gdzie to możliwe.	Niepowodzenie reguły Rectora.	Ograniczenia setterów obowiązują wyłącznie w czasie kompilacji i są usuwane w wygenerowanym wyniku.
DowngradeAsymmetricVisibilityRector::getRuleDefinition()	brak.	Zwraca metadane reguły Rectora oraz przykłady.	RuleDefinition	brak oczekiwanych.	Utrzymuje dokumentację reguły widoczną dla narzędzi Rectora.
DowngradeAsymmetricVisibilityRector::getNodeTypes()	brak.	Wybiera typy węzłów sprawdzane przez regułę.	array<class-string<Node>>	brak oczekiwanych.	Zakres powinien pozostać wąski na potrzeby deterministycznych przekształceń.
DowngradeAsymmetricVisibilityRector::refactor(Node $node)	Węzeł AST.	Konwertuje widoczność asymetryczną tam, gdzie występuje.	`Node	null`	Niepowodzenie reguły Rectora.
DowngradeCloneWithRector	clone() z nadpisaniami właściwości.	Klon z jawnymi przypisaniami właściwości.	Korzysta z wygenerowanych zmiennych tymczasowych.	Niepowodzenie reguły Rectora.	Musi działać po obniżeniach właściwości tylko do odczytu.
DowngradeCloneWithRector::getRuleDefinition()	brak.	Zwraca metadane reguły oraz przykłady.	RuleDefinition	brak oczekiwanych.	Wykorzystywane przez diagnostykę Rectora.
DowngradeCloneWithRector::getNodeTypes()	brak.	Wybiera węzły instrukcji return oraz wyrażeń.	array<class-string<Node>>	brak oczekiwanych.	Utrzymuje regułę skoncentrowaną na składni clone-with.
DowngradeCloneWithRector::refactor(Node $node)	Węzeł AST.	Przepisuje clone-with na klon wraz z przypisaniami.	`array	null`	Niepowodzenie reguły Rectora.
DowngradeTraitConstantsRector	Stałe traitów oraz odwołania do nich.	Właściwości statyczne oraz odwołania do właściwości.	Zachowuje widoczność tam, gdzie to możliwe.	Niepowodzenie reguły Rectora.	Usuwa final, ponieważ starsze właściwości nie mogą być final.
DowngradeTraitConstantsRector::getRuleDefinition()	brak.	Zwraca metadane reguły oraz przykłady.	RuleDefinition	brak oczekiwanych.	Wykorzystywane przez diagnostykę Rectora.
DowngradeTraitConstantsRector::getNodeTypes()	brak.	Wybiera węzły traitów oraz odczyty stałych klasy.	array<class-string<Node>>	brak oczekiwanych.	Ogranicza regułę do stałych traitów.
DowngradeTraitConstantsRector::refactor(Node $node)	Węzeł AST.	Przepisuje stałe traitów oraz odwołania na zgodne właściwości.	`Node	null`	Niepowodzenie reguły Rectora.

Kontrakt wygenerowanego pakietu

Skorzystaj z tej tabeli, aby zobaczyć, co generuje narzędzie kompilacji: nazwy pakietów instalowanych przez projekty zależne oraz pakiet zawierający dystrybucję Pro.

Wygenerowany pakiet	Rola w środowisku uruchomieniowym	Uwagi
nextpdf/backport	Wygenerowana dystrybucja uruchomieniowa o otwartym kodzie źródłowym.	Zastępuje wybrane pakiety nextpdf/* dla docelowego środowiska uruchomieniowego.
nextpdf/backport-pro	Wygenerowana zastrzeżona dystrybucja Pro, gdy obecne są źródła Pro.	Publikowana niezależnie od pakietu o otwartym kodzie źródłowym.

Uwagi dla programistów

• Narzędzie kompilacji pobiera wydania źródeł i generuje artefakty. Nie traktuj wygenerowanego wyniku jako źródła prawdy do modyfikacji.
• Każda reguła niestandardowa musi mieć testy z danymi przykładowymi, zanim trafi do potoku kompilacji.
• Zadania wydaniowe muszą walidować wygenerowany wynik w docelowym środowisku uruchomieniowym, nie tylko na hoście kompilacji.