Uruchamianie i wykrywanie w backporcie NextPDF

To narzędzie kompilacji — NIE zależność uruchomieniowa. Ta strona wyjaśnia, jak narzędzie kompilujące uruchamia się na hoście opiekuna projektu lub na hoście ciągłej integracji (CI). Aplikacje korzystające z biblioteki nigdy nie ładują tego kodu.

W skrócie

Narzędzie kompilujące nie korzysta z frameworka, kontenera wstrzykiwania zależności ani z automatycznego wykrywania dostawców usług. Zamiast tego skrypty PHP uruchamiane w interfejsie wiersza poleceń (CLI) są łączone za pomocą require_once oraz autoloadera PSR-4 Composera. Tutaj „wykrywanie” ma dwa konkretne znaczenia: które repozytoria źródłowe odczytuje etap scalania oraz jak orkiestrator wybiera konfigurację narzędzia Rector dla danego celu.

Przegląd potoku kompilacji

Orkiestratorem jest scripts/build.php. Rozpoczyna kompilację, a następnie wykonuje kolejno pięć etapów. Każdy etap działa jako bramka, więc pierwsze niepowodzenie zatrzymuje kompilację:

1. Scalanie źródeł — skopiowanie repozytoriów źródłowych do jednego drzewa.
2. Uruchomienie obniżenia wersji przez Rector — jeden przebieg dla PHP 8.1; dwa przebiegi wraz z poprawkami dla PHP 7.4.
3. Wygenerowanie composer.json — zapisanie wygenerowanego manifestu pakietu wraz z jego mapą replace.
4. Skopiowanie zasobów statycznych — skopiowanie licencji oraz wygenerowanego dziennika zmian.
5. Walidacja danych wyjściowych — zliczenie wyemitowanych plików PHP; właściwa bramka składni uruchamia się później w CI.

Zweryfikowano na podstawie scripts/build.php (run(), step()). Szczegóły dotyczące wyboru reguł znajdziesz na stronie /integrations/backport/configuration/, a opis bramki CI na stronie /integrations/backport/production-usage/.

Wykrywanie modułów źródłowych

Wykrywanie źródeł nie jest sterowane manifestem. scripts/merge-sources.php używa stałej mapy, w której kluczem jest nazwa repozytorium, a wybór zależy od celu.

Dla celu PHP 8.1 mapa obejmuje nextpdf (rdzeń), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter oraz nextpdf-Pro, jeśli Pro jest uwzględnione. Dla celu PHP 7.4 mapa zwęża się wyłącznie do nextpdf. Narzędzie kompilujące odnajduje każde repozytorium jako katalog równorzędny w katalogu głównym --source-dir. Weryfikuje każde oczekiwane repozytorium, zanim cokolwiek skopiuje. Jeśli któregoś brakuje, scalanie zostaje przerwane, a narzędzie zgłasza jego nazwę i ścieżkę. Zweryfikowano na podstawie scripts/merge-sources.php (MergeSources::__construct(), run()).

Scalanie umieszcza rdzeń w src/, a każdy adapter w jego podkatalogu z przestrzenią nazw (src/Artisan/, src/Laravel/ i tak dalej). Pro trafia do osobnego drzewa pro/src/, aby kompilacja mogła wyemitować Pro jako odrębny pakiet. Zweryfikowano na podstawie MergeSources (mergeCore(), mergeArtisan(), mergePro()).

Sekwencja uruchamiania

1. scripts/build.php działa w ramach SAPI dla CLI (interfejs programowania aplikacji serwera). Za pomocą require_once dołącza merge-sources.php oraz adjust-composer.php.
2. Punkt wejścia CLI odczytuje opcje za pomocą getopt() — --version, --source-dir, --output-dir, --target, --dry-run, --no-pro.
3. Tworzona jest instancja Build. Konstruktor waliduje --target względem ['php74', 'php81'] i zgłasza InvalidArgumentException dla nieprawidłowej wartości, zanim rozpoczną się jakiekolwiek prace. Dla celu PHP 7.4 wymusza dane wyjściowe obejmujące wyłącznie rdzeń i wyłącza Pro.
4. Build::run() wykonuje pięć etapów i kończy działanie ze statusem 0 w razie powodzenia albo 1 przy pierwszym niepowodzeniu.

Zweryfikowano na podstawie scripts/build.php (punkt wejścia CLI, Build::__construct(), run()).

Powiązania z kontenerem

Nie dotyczy. Narzędzie kompilujące jest narzędziem CLI. Nie ma kontenera wstrzykiwania zależności ani kontenera usług frameworka. Łączenie wykorzystuje jawne wywołania require_once oraz automatyczne ładowanie PSR-4 Composera dla NextPDF\Backport\ (reguły) oraz NextPDF\Backport\Scripts\ (skrypty). Zweryfikowano na podstawie composer.jsonautoload oraz instrukcji require_once w scripts/build.php.

Kolejność rozwiązywania konfiguracji

Nie ma pliku konfiguracyjnego. Konfiguracja pochodzi z flag CLI rozwiązywanych względem wartości domyślnych wbudowanych w skrypt:

1. Flaga CLI, jeśli została podana.
2. Wartość domyślna w bloku przetwarzania getopt() (na przykład domyślnym celem jest php81, a domyślną wersją 2.0.0).
3. Zachowanie wyprowadzone przez konstruktor z celu (PHP 7.4 wymusza wyłącznie rdzeń i brak Pro, niezależnie od --no-pro).

Zweryfikowano na podstawie scripts/build.php (punkt wejścia CLI oraz Build::__construct()). Pełny opis flag znajdziesz na stronie /integrations/backport/configuration/.

Diagnostyka

Orkiestrator udostępnia własną diagnostykę. Uruchom przebieg próbny (composer build:dry), aby wypisać repozytoria źródłowe, które zostałyby odczytane, oraz plan każdego etapu, bez zapisywania czegokolwiek. Każdy etap wypisuje znacznik powodzenia albo nazwane niepowodzenie. Nie ma osobnego podpolecenia diagnostycznego ani punktu wejścia bin/. Narzędzie kompilujące działa poprzez scripts/build.php lub jego aliasy w skryptach Composera. Zweryfikowano na podstawie scripts/build.php (step(), gałęzie dryRun), scripts/merge-sources.php (ścieżka przebiegu próbnego run()) oraz composer.jsonscripts.

Zobacz też

• /integrations/backport/overview/ — czym jest narzędzie kompilujące i co wytwarza.
• /integrations/backport/integration/ — kontrakt integracji z hostem kompilacji.
• /integrations/backport/configuration/ — konfiguracje narzędzia Rector oraz opis flag.
• /integrations/backport/troubleshooting/ — opis niepowodzeń etap po etapie.