NextPDF Backport Builder – Schnellstart

Build-Tooling – KEINE Laufzeitabhängigkeit. Diese Anleitung wird auf einem Maintainer- oder Continuous-Integration-Host (CI) ausgeführt. Das erzeugte Archiv ist das Artefakt, das ein nachgelagertes Projekt nutzt. Diese Schritte laufen niemals auf einem Anwendungsserver.

Auf einen Blick

Sie führen drei Dinge aus. Zuerst den Trockenlauf, der belegt, dass die Pipeline korrekt verbunden ist, ohne Dateien anzufassen. Danach folgt ein vollständiger PHP-8.1-Build, anschließend ein vollständiger PHP-7.4-Build. Jeder Schritt ist ein einzelner Befehl und stützt sich auf ein Composer-Skript oder einen dokumentierten scripts/build.php-Aufruf.

Voraussetzungen

• Ein Build-Host mit PHP >=8.4 <9.0, auf dem die Build-Abhängigkeiten installiert sind (composer install, ohne --no-dev). Siehe /integrations/backport/install/.
• Die Quell-Repositorys müssen als Geschwisterverzeichnisse unter einem gemeinsamen Quellwurzelverzeichnis ausgecheckt sein. Der PHP-8.1-Build liest nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter und nextpdf-Pro (für Pro). Der PHP-7.4-Build liest nur nextpdf. Verifiziert anhand von scripts/merge-sources.php.

Schritt 1 – Trockenlauf

Der Trockenlauf führt jede Stufe ausschließlich im Berichtsmodus aus. Das Zusammenführen listet auf, was es kopieren würde. Der Rector-Schritt wird gemeldet, aber nicht ausgeführt. Die Stufen für Composer-Generierung, Asset-Kopie und Validierung melden, was sie tun würden. Es wird nichts geschrieben. Führen Sie diesen Schritt zuerst aus, um zu bestätigen, dass Ihr Quell-Layout und Ihre Flags korrekt sind, denn er ist die schnellste Prüfung.

composer build:dry

composer build:dry wird zu php scripts/build.php --dry-run aufgelöst. Verifiziert anhand von composer.jsonscripts und scripts/build.php (der dryRun-Zweig in jeder Stufe). Mit den Standard-Flags ist das Ziel php81, und das Quellwurzelverzeichnis entspricht dem Skript-Standardwert. Sie können beides überschreiben, wie in Schritt 2 gezeigt.

Wenn der Trockenlauf ein fehlendes Quell-Repository meldet, bricht er sofort ab und nennt das Repository. Korrigieren Sie das Quell-Layout, bevor Sie fortfahren – siehe /integrations/backport/troubleshooting/.

Schritt 2 – vollständiger PHP-8.1-Build

Der PHP-8.1-Build durchläuft mehrere Schritte nacheinander. Er führt den Core mit den Framework-Adaptern und der tcpdf-Kompatibilitätsschicht zusammen, führt die einstufige Rector-Konfiguration aus, erzeugt die nextpdf/backportcomposer.json, kopiert die Lizenz, schreibt eine CHANGELOG.md und zählt die ausgegebenen PHP-Dateien.

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

Verifiziert anhand des CLI-Einstiegspunkts scripts/build.php. Die fünf Stufen laufen der Reihe nach: Quellen zusammenführen, Rector-Downgrade ausführen, composer.json generieren, statische Assets kopieren, Ausgabe validieren. Jede Stufe gibt bei Erfolg ein Häkchen aus. Die erste Stufe, die fehlschlägt, stoppt den Build und gibt ihren Fehler aus. Um Pro auszuschließen, fügen Sie --no-pro hinzu.

Bei Erfolg gibt der Orchestrator die verstrichene Zeit und den Ausgabepfad aus. Wenn Pro enthalten ist, gibt er außerdem den Pro-Ausgabepfad aus. Das Ausgabeverzeichnis enthält dann src/, tests/, eine generierte composer.json, die die replace-Map und die Polyfill-Anforderungen deklariert, LICENSE und CHANGELOG.md.

Schritt 3 – vollständiger PHP-7.4-Build

Der PHP-7.4-Build umfasst nur den Core und durchläuft die zweistufige Pipeline. Die Pipeline besteht aus der Enum-Vorverarbeitung, dem Leeren des Caches, den Post-Rector-Korrekturen und anschließend dem vollständigen Downgrade.

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

Verifiziert anhand von scripts/build.php. Hier erzwingt --target=php74 nur den Core und deaktiviert Pro, und runRector() wählt den zweistufigen Pfad. Die generierte composer.json trägt die Einschränkung >=7.4 <8.1, ersetzt nur nextpdf/core und fügt die Polyfills für PHP 8.0 und 8.1 zusätzlich zu den 8.2–8.5-Polyfills hinzu.

Schritt 4 – die Ausgabe lesen

Die Validierungsstufe zählt die PHP-Dateien in output/src und schlägt fehl, wenn die Anzahl null ist. Sie führt lokal keine Syntaxprüfung aus, weil der lokale Interpreter das moderne PHP des Build-Hosts ist und nicht die Zielversion. Sie gibt den Docker-Befehl für die Validierung in der tatsächlichen Ziellaufzeitumgebung aus. Verifiziert anhand von scripts/build.php (validateOutput()).

Führen Sie die Syntaxprüfung unter dem Ziel-PHP aus, um vollständig zu validieren. Der Release-Workflow tut genau das. Er prüft die Syntax der Ausgabe unter PHP 8.1 (oder PHP 7.4), installiert sie dann und testet sie über die gesamte Support-Matrix. Siehe /integrations/backport/production-usage/.

Was Sie erstellt haben

Artefakt	Erstellt von	Einschränkung	Ersetzt
nextpdf/backport (PHP 8.1)	Schritt 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro (PHP 8.1)	Schritt 2, wenn Pro enthalten ist	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (PHP 7.4)	Schritt 3	>=7.4 <8.1	nextpdf/core

Verifiziert anhand von scripts/adjust-composer.php.

Nächste Schritte

• /integrations/backport/production-usage/ – binden Sie dies in den ereignisgesteuerten Release-Workflow ein.
• /integrations/backport/configuration/ – die Regel- und Flag-Referenz zu diesen Befehlen.
• /integrations/backport/troubleshooting/ – jeder Stufenfehler mit seiner Bedeutung.