Fehlerbehebung beim NextPDF Backport Builder

Build-Werkzeuge — KEINE Laufzeitabhängigkeit. Jedes Symptom auf dieser Seite ist eine Buildzeitbedingung auf einem Maintainer- oder CI-Host. Keine dieser Bedingungen tritt in einer nachgelagerten Anwendung auf.

Auf einen Blick

Der Build durchläuft fünf Stufen in fester Reihenfolge. Er hält beim ersten Fehler an und gibt den Namen der Stufe sowie die Meldung aus. Ermitteln Sie die Stufe und suchen Sie die Ursache anschließend weiter unten. Die Stufen sind: Quellen zusammenführen, Rector-Downgrade ausführen, composer.json generieren, statische Assets kopieren und Ausgabe validieren. Geprüft anhand von scripts/build.php (run() und step()).

Stufe: Quellen zusammenführen

”Source repo '' not found at: ”

Die Zusammenführung validiert jedes erwartete Quell-Repository vor dem Kopieren. Sie bricht ab und nennt Namen und Pfad des fehlenden Repositorys. Das PHP-8.1-Ziel erwartet nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter und — falls Pro enthalten ist — nextpdf-Pro. Das PHP-7.4-Ziel erwartet nur nextpdf. Geprüft anhand von scripts/merge-sources.php (Validierungsschleife run(), Repository-Map __construct()).

Lösung: Checken Sie die Repositorys als gleichgeordnete Verzeichnisse unterhalb des an --source-dir übergebenen Pfads aus und verwenden Sie dabei die exakten Verzeichnisnamen von oben. Ein Probelauf listet jedes Repository auf, das gelesen würde. Verwenden Sie ihn, um das Layout vor einem vollständigen Build zu prüfen.

Stufe: Rector-Downgrade ausführen

Rector beendet sich mit einem Exit-Code ungleich null

Der Orchestrator meldet Rector failed on <label> (exit code: N) und hält an. Das Label gibt an, welcher Durchlauf fehlgeschlagen ist — public package, pro package, enum pre-processing oder full downgrade. Geprüft anhand von scripts/build.php (runRectorPass()).

Absturz des Standardparameter-Resolvers bei Enum-Standardwerten (PHP 7.4)

Deshalb ist das PHP-7.4-Ziel zweistufig. Der Resolver von Rector für Standardparameterwerte stürzt bei einem Enum-Case ab, der als Standardwert einer Konstruktor-Promotion verwendet wird. Durchlauf 1 (rector-php74-enums.php) wandelt Enums zunächst in Konstantenlisten-Klassen um. Der vollständige Durchlauf 2 trifft dadurch nicht mehr auf einen Enum-Case-Standardwert. Wenn Sie den Orchestrator umgehen und die vollständige PHP-7.4-Konfiguration direkt gegen Quellcode mit Enums ausführen, ist mit diesem Absturz zu rechnen. Geprüft anhand von scripts/build.php (Kommentar zu runRector() und zweistufige Sequenz) und rector/config/rector-php74-enums.php.

Benchmark-Skripte bringen Rector zum Absturz

rector-php81.php und rector-php74.php überspringen */tests/Benchmark/*. Diese Skripte verweisen auf externe PDF-Bibliotheken, die Rector nicht auflösen kann, was den Standardparameter-Resolver zum Absturz bringt. Wird ein Benchmark-Pfad verarbeitet, fehlt das Skip-Glob oder der Pfad weicht ab. Geprüft anhand der withSkip()-Aufrufe.

MHASH_XXH*-Absturz (PHP 7.4)

rector-php74.php überspringt DowngradeHashAlgorithmXxHashRector. Diese integrierte Regel stürzt bei den xxHash-Konstanten ab. Da der Quellcode xxHash nicht verwendet, ist das Überspringen unbedenklich. Geprüft anhand von rector/config/rector-php74.php (withSkip()).

Stufe: Nachbearbeitungen nach Rector (nur PHP 7.4)

Die Nachbearbeitungen laufen zwischen den beiden Durchläufen. Sie schreiben Muster um, die die Enum-zu-Klasse-Regel zurücklässt. Wenn die PHP-7.4-Ausgabe einen Parse-Fehler aufweist, der EnumClass::Case->value, ->name, eine frühere Enum-Methode, die als Instanzmethode aufgerufen wird, oder ein benanntes Argument an einem nicht aufgelösten Typ betrifft, hat die Nachbearbeitung das betreffende Muster nicht erfasst. Die Clone-with-Einschränkung gilt auch hier: Der Argumentabgleich ist nicht rekursiv, sodass ein Überschreibungswert mit verschachtelten Klammern nicht umgeschrieben wird. Geprüft anhand von scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) und rector/rules/DowngradeCloneWithRector.php (dokumentierte Einschränkung).

Stufe: composer.json generieren

Diese Stufe verschiebt die verarbeiteten Verzeichnisse src/ und tests/ aus dem Build-Temp-Verzeichnis in das Ausgabeverzeichnis. Anschließend schreibt sie die generierte composer.json. Ein Fehler an dieser Stelle ist fast immer auf eine Dateisystembedingung zurückzuführen: Das Ausgabeverzeichnis ist nicht beschreibbar oder der Build-Temp-Verzeichnisbaum fehlt, weil Rector nichts erzeugt hat. Geprüft anhand von scripts/build.php (adjustComposer(), moveTree()).

Stufe: statische Assets kopieren

Diese Stufe kopiert LICENSE aus dem Core-Quell-Repository und schreibt eine generierte CHANGELOG.md. Wenn die Lizenz fehlt, wird das Kopieren stillschweigend übersprungen und der Build fortgesetzt; das Changelog wird immer geschrieben. Ein Fehler an dieser Stelle weist darauf hin, dass das Ausgabeverzeichnis während des Builds nicht mehr beschreibbar wurde. Geprüft anhand von scripts/build.php (copyStaticAssets()).

Stufe: Ausgabe validieren

”Output src/ directory not found” / “No PHP files found in output”

Die Validierung erfordert ein nicht leeres output/src-Verzeichnis. Ein leerer Verzeichnisbaum bedeutet, dass die Zusammenführung nichts kopiert hat oder das Verschieben der Dateien fehlgeschlagen ist. Geprüft anhand von scripts/build.php (validateOutput()).

”Syntax validation: skipped (requires PHP runtime)”

Dies ist erwartetes Verhalten, kein Fehler. Der Build-Host führt ein modernes PHP aus, nicht die Ziellaufzeit; deshalb zählt die lokale Stufe nur Dateien und gibt den Docker-Befehl für eine echte Syntaxprüfung aus. Das maßgebliche Syntax-Gate ist der php -l-Schritt nach dem Build im Release-Workflow, der unter der tatsächlichen Ziellaufzeitumgebung ausgeführt wird. Geprüft anhand von scripts/build.php (validateOutput()) und .github/workflows/build.yml (die PHP-8.1-/PHP-7.4-Syntaxprüfungsschritte).

Bekannte Einschränkungen

Diese Einschränkungen sind dem Downgrade-Ansatz inhärent. Sie sind anhand der Regeln und des Abschnitts “Known Limitations” der Projekt-README.md geprüft:

• Readonly-Eigenschaften werden entfernt. readonly wird entfernt, damit die explizite Eigenschaftszuweisung der Clone-with-Expansion auf der älteren Laufzeitumgebung zulässig ist. In der heruntergestuften Ausgabe erzwingt die Laufzeitumgebung die Unveränderlichkeit nicht mehr.
• #[Override] wird auf PHP 8.1 nicht erzwungen. Das Attribut kann verbleiben, aber die ältere Laufzeitumgebung reagiert nicht darauf.
• Das PHP-7.4-Ziel umfasst nur den Core. Framework-Adapter, die tcpdf-Kompatibilitätsschicht und Pro sind wegen des Aufbaus des Build-Skripts nicht Teil der PHP-7.4-Distribution.
• Pro ist ein separates Paket und nur für PHP 8.1 verfügbar. Es gibt keinen PHP-7.4-Pro-Build.
• Der Argumentabgleich von Clone-with ist nicht rekursiv. Überschreibungswerte mit verschachtelten Klammern werden nicht transformiert, und nur String-Array-Schlüssel werden zu Eigenschaftsnamen aufgelöst.

Weiter

• /integrations/backport/configuration/ — die Referenz der Regeln und Flags.
• /integrations/backport/production-usage/ — das CI-Gate und die Release-Lanes.