Przegląd NextPDF Backport Builder
Narzędzie kompilacyjne, nie zależność uruchomieniowa. Opiekunowie NextPDF używają tego pakietu do tworzenia dystrybucji NextPDF zgodnych z PHP 8.1+ i PHP 7.4+. Aplikacje nigdy nie mogą dodawać tego pakietu jako zależności uruchomieniowej.
W skrócie
Dział zatytułowany „W skrócie”NextPDF Backport Builder to infrastruktura kompilacji służąca do tworzenia obniżonej (downgraded) dystrybucji ekosystemu NextPDF dla środowisk uruchomieniowych PHP starszych niż bazowa wersja używana podczas tworzenia oprogramowania. NextPDF jest pisany z myślą o nowoczesnej wersji PHP i używa składni, którą wcześniejsze interpretery odrzucają. Builder przetwarza kod źródłowy za pomocą Rector, silnika przekształcającego abstrakcyjne drzewa składniowe, i generuje pakiety, których składnię akceptuje środowisko uruchomieniowe PHP 8.1 lub PHP 7.4.
Nazwa pakietu w Composerze to nextpdf/backport-builder. Deklaruje "type": "project" i nie wprowadza żadnej zależności uruchomieniowej od NextPDF. Jego wymagania ograniczają się do silnika kompilacji (rector/rector), analizy statycznej (phpstan/phpstan), narzędzia uruchamiającego testy (phpunit/phpunit) oraz zestawu pakietów symfony/polyfill-* używanych w generowanym wyniku. Potwierdza to plik composer.json w katalogu głównym repozytorium.
Czym ten pakiet nie jest
Dział zatytułowany „Czym ten pakiet nie jest”To repozytorium nie zawiera silnika NextPDF. Zawiera reguły i skrypty, które przekształcają ten silnik do postaci backportowanej. To rozdzielenie ma trzy praktyczne konsekwencje:
- Tego pakietu nie instaluje się po to, aby renderować pliki PDF. Zainstaluj
nextpdf/backport, artefakt generowany przez ten builder. Builder trzymaj na hoście opiekuna lub na hoście ciągłej integracji (CI). - Nie programuje się w oparciu o wygenerowany kod. Wygenerowana dystrybucja jest artefaktem tworzonym maszynowo, tylko do odczytu. Zgłoszenia błędów i propozycje funkcji kieruj do pierwotnych repozytoriów źródłowych
nextpdf/*. - Wynik jest publikowany jako tagi wersji, a nie jako gałęzie tego repozytorium. Potok wydawniczy taguje wygenerowane drzewo i dołącza archiwa do wydania na GitHub.
Co generuje
Dział zatytułowany „Co generuje”Builder generuje pakiety Composera, których nazwy i licencje ustala scripts/adjust-composer.php:
| Generowany pakiet | Licencja | Zakres | Kompilowany, gdy |
|---|---|---|---|
nextpdf/backport | Apache-2.0 | Rdzeń, adaptery frameworków oraz warstwa zgodności z tcpdf dla celu PHP 8.1 | Zawsze |
nextpdf/backport-pro | proprietary | Moduł Pro, generowany jako osobny pakiet | Cel PHP 8.1, gdy źródło Pro jest obecne i Pro nie jest wykluczone |
Pakiet nextpdf/backport deklaruje wpisy replace Composera, tak aby po instalacji spełniał ograniczenia oryginalnych pakietów. Dla celu PHP 8.1 zastępowane są pakiety nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter oraz nextpdf/compat-legacy. Dla celu PHP 7.4 zastępowany jest tylko nextpdf/core, ponieważ kompilacja PHP 7.4 obejmuje wyłącznie rdzeń. Potwierdza to scripts/adjust-composer.php (buildReplace()).
Autoloader po stronie konsumenta rozwiązuje scalone drzewo przez jeden prefiks PHP Standards Recommendation 4 (PSR-4), NextPDF\, odwzorowany na src/. PSR-4 odwzorowuje prefiks przestrzeni nazw na katalog bazowy i rozwiązuje każdą w pełni kwalifikowaną nazwę klasy do pliku znajdującego się pod nim; zobacz PHP Framework Interop Group (PHP-FIG) PSR-4. Pakiet Pro odwzorowuje NextPDF\Pro\ na własny src/.
Macierz obsługiwanych wersji PHP
Dział zatytułowany „Macierz obsługiwanych wersji PHP”Poniższa macierz obejmuje wyłącznie to, co wymuszają konfiguracje Rector oraz skrypty kompilacji. Host kompilacji zawsze działa na nowoczesnej wersji PHP. Wynik jest przeznaczony dla starszej wersji.
| Zagadnienie | Wartość | Dowód |
|---|---|---|
| PHP hosta kompilacji | >=8.4 <9.0 | composer.jsonrequire.php |
| PHP do build/test w CI | 8.5 | .github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5') |
| Ograniczenie wyniku dla celu PHP 8.1 | >=8.1 <8.5 | scripts/adjust-composer.php (generatePublicComposer()) |
| Ograniczenie wyniku dla celu PHP 7.4 | >=7.4 <8.1 | scripts/adjust-composer.php (generatePublicComposer()) |
| Zakres celu PHP 8.1 | Rdzeń + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, osobno) | scripts/merge-sources.php, scripts/adjust-composer.php |
| Zakres celu PHP 7.4 | Tylko rdzeń | scripts/build.php (--target=php74 wymusza wyłącznie rdzeń, Pro wyłączone) |
Kompilacja PHP 8.1 jest weryfikowana na PHP 8.1, 8.2, 8.3 oraz 8.4. Kompilacja PHP 7.4 jest weryfikowana na PHP 7.4 oraz 8.0. Potwierdzają to macierze zadań validate-php81 oraz validate-php74 w .github/workflows/build.yml. Są to środowiska uruchomieniowe wykorzystywane przez potok. Stanowią zaobserwowany zbiór weryfikacyjny, a nie deklarację zgodności.
Model dwóch gałęzi
Dział zatytułowany „Model dwóch gałęzi”To repozytorium nie ma gałęzi main. PHP74 to gałąź domyślna, a PHP81 to druga gałąź trwała. Wybrana gałąź określa dwie rzeczy: domyślny cel lokalnej kompilacji oraz scalany zestaw źródeł. Zmianę, która dotyczy obu celów, zastosuj w każdej gałęzi przez osobny pull request. Przepływ pracy CI działa zarówno na PHP74, jak i na PHP81. Potwierdza to git branch -a oraz .github/workflows/0-ci.yml (branches: [PHP74, PHP81]).
Jak przebiega wydanie
Dział zatytułowany „Jak przebiega wydanie”Ścieżka wydania jest sterowana zdarzeniami. Gdy organizacja źródłowa NextPDF publikuje tag wydania, zdarzenie repository-dispatch typu source-release wyzwala przepływ pracy kompilacji. Przepływ pracy pobiera każde repozytorium źródłowe dla pasującego tagu, uruchamia potok, sprawdza składnię wyniku w docelowym środowisku uruchomieniowym, weryfikuje go w całej macierzy wsparcia oraz dołącza archiwa do wydania na GitHub. Tag wersji jest zgodny z Semantic Versioning: numer wersji ma postać MAJOR.MINOR.PATCH w odniesieniu do zadeklarowanego publicznego API (Semantic Versioning 2.0.0 §2). Potwierdza to .github/workflows/build.yml.
Co dalej
Dział zatytułowany „Co dalej”- /integrations/backport/install/ — jak zainstalować builder na hoście kompilacji oraz jak konsumenci instalują wygenerowany pakiet.
- /integrations/backport/configuration/ — konfiguracje Rector, reguły niestandardowe oraz flagi kompilacji.
- /integrations/backport/quickstart/ — próbne uruchomienie oparte na źródłach oraz pełne wywołanie kompilacji.
- /integrations/backport/production-usage/ — jak wpiąć builder w przepływ pracy wydania.
- /integrations/backport/troubleshooting/ — tryby awarii, przed którymi zabezpiecza się potok, oraz jak je odczytywać.
- /integrations/backport/security-and-operations/ — podejście do łańcucha dostaw, granica zaufania oraz gwarancje operacyjne.
- /integrations/backport/boot-and-discovery/ — jak builder wykrywa moduły źródłowe i uruchamia się.
- /integrations/backport/integration/ — kontrakt integracji z hostem kompilacji.