Szybki start z NextPDF Backport Builder

Narzędzia do kompilacji — nie zależność środowiska uruchomieniowego. Wykonaj te instrukcje na hoście opiekuna projektu lub na hoście ciągłej integracji (CI). Wytworzone archiwum wykorzystuje projekt zależny. Tych kroków nigdy nie wykonuje się na serwerze aplikacji.

W skrócie

Wykonaj trzy polecenia. Najpierw uruchom przebieg próbny, aby potwierdzić, że potok jest poprawnie połączony, bez modyfikowania plików. Następnie uruchom pełną kompilację dla PHP 8.1. Na koniec uruchom pełną kompilację dla PHP 7.4. Każdy krok używa jednego polecenia opartego na skrypcie Composer albo na udokumentowanym wywołaniu scripts/build.php.

Wymagania wstępne

• Host kompilacji z PHP >=8.4 <9.0 z zainstalowanymi zależnościami kompilacji (composer install, bez --no-dev). Zobacz /integrations/backport/install/.
• Repozytoria źródłowe pobrane jako katalogi równorzędne w obrębie jednego katalogu głównego źródeł. Kompilacja dla PHP 8.1 odczytuje nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter oraz nextpdf-Pro (dla wersji Pro). Kompilacja dla PHP 7.4 odczytuje wyłącznie nextpdf. Zweryfikowano na podstawie scripts/merge-sources.php.

Krok 1 — przebieg próbny

Przebieg próbny wykonuje każdy etap wyłącznie w trybie raportowania. Etap scalania wypisuje listę plików, które zostałyby skopiowane. Polecenie zapowiada krok Rector, ale go nie uruchamia. Etapy generowania pliku composer, kopiowania zasobów oraz walidacji wypisują planowany przebieg. Nic nie jest zapisywane. Uruchom go w pierwszej kolejności, bo to najszybszy sposób na potwierdzenie układu źródeł i flag.

composer build:dry

composer build:dry przekłada się na php scripts/build.php --dry-run. Zweryfikowano na podstawie composer.jsonscripts oraz scripts/build.php (gałąź dryRun w każdym etapie). Przy domyślnych flagach celem jest php81, a katalog główny źródeł korzysta z wartości domyślnej skryptu. Każdą z tych wartości można zmienić, jak pokazano w kroku 2.

Jeśli przebieg próbny zgłosi brakujące repozytorium źródłowe, zatrzymuje się natychmiast i podaje nazwę tego repozytorium. Popraw układ źródeł, zanim przejdziesz dalej. Zobacz /integrations/backport/troubleshooting/.

Krok 2 — pełna kompilacja dla PHP 8.1

Kompilacja dla PHP 8.1 wykonuje kilka kroków po kolei. Scala rdzeń z adapterami frameworków oraz warstwą zgodności tcpdf. Uruchamia Rector w konfiguracji jednoprzebiegowej. Generuje nextpdf/backportcomposer.json. Kopiuje licencję, zapisuje CHANGELOG.md oraz zlicza wygenerowane pliki PHP.

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

Zweryfikowano na podstawie punktu wejścia interfejsu wiersza poleceń (CLI) scripts/build.php. Pięć etapów wykonuje się po kolei: scalenie źródeł, uruchomienie obniżenia wersji w Rector, wygenerowanie composer.json, skopiowanie zasobów statycznych, walidacja wyniku. Każdy etap po pomyślnym zakończeniu wypisuje znacznik wyboru. Pierwszy nieudany etap zatrzymuje kompilację i wypisuje swój błąd. Aby wykluczyć wersję Pro, dodaj --no-pro.

Po pomyślnym zakończeniu orkiestrator wypisuje czas trwania oraz ścieżkę wyjściową. Gdy uwzględniono wersję Pro, wypisuje również ścieżkę wyjściową wersji Pro. Katalog wyjściowy zawiera wówczas src/, tests/, wygenerowany composer.json, który deklaruje mapę replace oraz wymagania polyfilli, LICENSE oraz CHANGELOG.md.

Krok 3 — pełna kompilacja dla PHP 7.4

Kompilacja dla PHP 7.4 obejmuje wyłącznie rdzeń i korzysta z dwuprzebiegowego potoku. Wykonuje wstępne przetwarzanie wyliczeń, czyści pamięć podręczną, stosuje poprawki po użyciu Rector, a następnie przeprowadza pełne obniżenie wersji.

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

Zweryfikowano na podstawie scripts/build.php. Tutaj --target=php74 wymusza tryb wyłącznie rdzenia, wyłącza wersję Pro i sprawia, że runRector() wybiera ścieżkę dwuprzebiegową. Wygenerowany composer.json zawiera ograniczenie >=7.4 <8.1. Zastępuje wyłącznie nextpdf/core i dodaje polyfille dla PHP 8.0 i 8.1 oprócz polyfilli dla wersji 8.2–8.5.

Krok 4 — odczyt wyniku

Etap walidacji zlicza pliki PHP w output/src i kończy się niepowodzeniem, gdy liczba ta wynosi zero. Nie uruchamia lokalnego sprawdzania składni. Lokalny interpreter to nowoczesny PHP hosta kompilacji, a nie docelowe środowisko uruchomieniowe. Zamiast tego wypisuje polecenie Docker służące do walidacji w rzeczywistym docelowym środowisku uruchomieniowym. Zweryfikowano na podstawie scripts/build.php (validateOutput()).

Aby przeprowadzić pełną walidację, uruchom sprawdzenie składni pod docelowym PHP. Proces wydania używa tej samej ścieżki. Sprawdza składnię wyniku pod PHP 8.1 (lub PHP 7.4), a następnie instaluje go i testuje w całej macierzy wsparcia. Zobacz /integrations/backport/production-usage/.

Co zostało zbudowane

Artefakt	Zbudowane przez	Ograniczenie	Zastępuje
nextpdf/backport (PHP 8.1)	Krok 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro (PHP 8.1)	Krok 2, gdy uwzględniono wersję Pro	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (PHP 7.4)	Krok 3	>=7.4 <8.1	nextpdf/core

Zweryfikowano na podstawie scripts/adjust-composer.php.

Dalej

• /integrations/backport/production-usage/ — włącz to do sterowanego zdarzeniami procesu wydania.
• /integrations/backport/configuration/ — opis reguł i flag stojących za tymi poleceniami.
• /integrations/backport/troubleshooting/ — opis każdego niepowodzenia etapu i jego znaczenia.