NextPDF-Backport: Boot und Discovery

Build-Tooling — KEINE Laufzeitabhängigkeit. Dieses Dokument beschreibt, wie der Builder auf einem Maintainer- oder CI-Host gestartet wird. Downstream-Anwendungen laden diesen Code niemals.

Auf einen Blick

Der Builder hat kein Framework, keinen Dependency-Injection-Container und keine Service-Provider-Auto-Discovery. Er ist eine Sammlung von PHP-CLI-Skripten, die über require_once und den PSR-4-Autoloader von Composer verdrahtet sind. „Discovery” bedeutet hier zwei konkrete Dinge: welche Quell-Repositories die Merge-Stufe einliest und wie der Orchestrator die Rector-Konfiguration für das Ziel auswählt.

Überblick über die Build-Pipeline

Der Orchestrator ist scripts/build.php. Er startet den Builder und führt danach fünf geordnete Stufen aus. Jede Stufe ist so abgesichert, dass der erste Fehler den Build stoppt:

1. Quellen zusammenführen — die Quell-Repositories in einen Baum kopieren.
2. Rector-Downgrade ausführen — ein einzelner Durchlauf für PHP 8.1; zwei Durchläufe plus Nacharbeiten für PHP 7.4.
3. composer.json erzeugen — das erzeugte Paketmanifest mit seiner replace-Map schreiben.
4. Statische Assets kopieren — Lizenz und ein generiertes Changelog.
5. Ausgabe validieren — die ausgegebenen PHP-Dateien zählen; das maßgebliche Syntax-Gate läuft später in der CI.

Verifiziert gegen scripts/build.php (run(), step()). Die Details zur Regelauswahl finden sich in /integrations/backport/configuration/; das CI-Gate in /integrations/backport/production-usage/.

Discovery der Quellmodule

Die Quellen-Discovery ist nicht manifestgesteuert. Stattdessen verwendet scripts/merge-sources.php eine feste Map, deren Schlüssel die Repository-Namen sind und deren Inhalt vom Ziel abhängt.

Für das PHP-8.1-Ziel enthält die Map nextpdf (Core), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter und nextpdf-Pro, sofern Pro einbezogen ist. Für das PHP-7.4-Ziel enthält die Map ausschließlich nextpdf. Jedes Repository wird als Geschwisterverzeichnis unterhalb des Roots von --source-dir aufgelöst. Jedes erwartete Repository wird vor dem ersten Kopiervorgang validiert; fehlt eines, bricht der Merge mit dessen Namen und Pfad ab. Verifiziert gegen scripts/merge-sources.php (MergeSources::__construct(), run()).

Der Merge legt den Core unter src/ ab und jeden Adapter in seinem Namespace-bezogenen Unterverzeichnis (src/Artisan/, src/Laravel/ usw.). Pro wird in einem separaten pro/src/-Baum abgelegt, damit es als eigenes Paket ausgegeben werden kann. Verifiziert gegen MergeSources (mergeCore(), mergeArtisan(), mergePro()).

Boot-Sequenz

1. scripts/build.php wird unter der CLI-SAPI aufgerufen. Das Skript bindet merge-sources.php und adjust-composer.php per require_once ein.
2. Der CLI-Einstiegspunkt liest Optionen mit getopt() — --version, --source-dir, --output-dir, --target, --dry-run, --no-pro.
3. Eine Build-Instanz wird angelegt. Der Konstruktor validiert --target gegen ['php74', 'php81'] und löst bei einem ungültigen Wert eine InvalidArgumentException aus, bevor die Arbeit beginnt. Für das PHP-7.4-Ziel erzwingt er nur den Core und deaktiviert Pro.
4. Build::run() führt die fünf Stufen aus und endet bei Erfolg mit Status 0, beim ersten Fehler mit 1.

Verifiziert gegen scripts/build.php (CLI-Einstiegspunkt, Build::__construct(), run()).

Container-Bindings

Nicht zutreffend. Der Builder ist ein CLI-Tool ohne Dependency-Injection-Container und ohne Framework-Service-Container. Die Verdrahtung erfolgt über explizites require_once plus Composer-PSR-4-Autoloading von NextPDF\Backport\ (Regeln) und NextPDF\Backport\Scripts\ (Skripte). Verifiziert gegen composer.jsonautoload und die require_once-Anweisungen in scripts/build.php.

Auflösungsreihenfolge der Konfiguration

Es gibt keine Konfigurationsdatei. Die Konfiguration besteht aus den CLI-Flags, die gegen die im Skript fest verankerten Standardwerte aufgelöst werden:

1. Das CLI-Flag, sofern angegeben.
2. Der Standardwert im getopt()-Parsing-Block (zum Beispiel ist target standardmäßig php81 und version 2.0.0).
3. Verhalten, das der Konstruktor aus dem Ziel ableitet (PHP 7.4 erzwingt nur den Core und kein Pro, unabhängig von --no-pro).

Verifiziert gegen scripts/build.php (CLI-Einstiegspunkt und Build::__construct()). Die vollständige Flag-Referenz findet sich in /integrations/backport/configuration/.

Diagnose

Der Orchestrator dient selbst als Diagnose-Oberfläche. Führen Sie einen Dry-Run (composer build:dry) aus, um – ohne etwas zu schreiben – die Quell-Repositories auszugeben, die gelesen würden, sowie die geplante Aktion jeder Stufe. Jede Stufe gibt ein Erfolgshäkchen oder einen benannten Fehler aus. Es gibt keinen separaten Diagnose-Unterbefehl und keinen bin/-Einstiegspunkt. Der Builder wird über scripts/build.php oder seine Composer-Script-Aliasse aufgerufen. Verifiziert gegen scripts/build.php (step(), die dryRun-Zweige), scripts/merge-sources.php (run() Dry-Run-Pfad) und composer.jsonscripts.

Siehe auch

• /integrations/backport/overview/ — was der Builder ist und was er produziert.
• /integrations/backport/integration/ — der Build-Host-Integrationsvertrag.
• /integrations/backport/configuration/ — Rector-Konfigurationen und die Flag-Referenz.
• /integrations/backport/troubleshooting/ — stufenweise Fehlerreferenz.