API-Referenz des Backport Builders
Auf einen Blick
Abschnitt betitelt „Auf einen Blick“Der Backport Builder ist ein Build-Werkzeug, keine Laufzeitbibliothek. Seine öffentliche Schnittstelle umfasst die Build-Befehle (scripts/build.php und die zugehörigen composer build*-Wrapper), die vier dahinterliegenden Skriptklassen (Build, MergeSources, AdjustComposer, ValidateBuildContract), die drei Rector-Konfigurationsdateien, die drei eigenen Rector-Regeln und den Vertrag des erzeugten Pakets (nextpdf/backport und nextpdf/backport-pro). Sie führen ihn auf einem Build- oder CI-Host aus, um modernen NextPDF-Quellcode in eine herabgestufte Distribution umzuwandeln. Sie binden ihn niemals in eine Anwendung ein.
Beginnen Sie hier: Wenn Sie neu einsteigen, führen Sie composer build:dry aus (was zu php scripts/build.php --dry-run aufgelöst wird). Der Befehl durchläuft jede Stufe im reinen Berichtsmodus, ohne Dateien zu schreiben, sodass Sie Quelllayout und Flags vor einem echten Build prüfen können. Das erste Beispiel unter „Häufige Aufgaben“ zeigt genau diesen Ablauf.
Häufige Aufgaben
Abschnitt betitelt „Häufige Aufgaben“Am häufigsten nutzen Sie dieses Paket für Build-Aufrufe auf einem Build-Host. Jedes der folgenden Beispiele ist ein einzelner Befehl und wurde mit scripts/build.php und composer.json abgeglichen.
Prüfen Sie die Pipeline, ohne etwas zu schreiben (sicherer erster Lauf):
composer build:dryDer Wrapper wird zu php scripts/build.php --dry-run aufgelöst: Der Befehl führt Merge, Rector, Composer-Erzeugung, Asset-Kopie und Validierung im reinen Berichtsmodus aus und kopiert nichts.
Erzeugen Sie die vollständige PHP 8.1-Distribution (nextpdf/backport, plus nextpdf/backport-pro, wenn Pro-Quellcode vorhanden ist):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./outputDer Befehl führt Core sowie die Framework-Adapter und die tcpdf-Kompatibilitätsschicht zusammen, führt den einzelnen Rector-Durchlauf für das PHP 8.1-Ziel aus und schreibt den erzeugten Paketbaum nach ./output. Fügen Sie --no-pro hinzu, um das Pro-Paket zu überspringen.
Erzeugen Sie die Core-only-PHP 7.4-Distribution (die zweistufige Enum-Pipeline):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./output-php74 \ --target=php74--target=php74 erzwingt eine Core-only-Ausgabe und deaktiviert Pro, führt dann die Enum-Vorverarbeitung, die Nachbesserungen nach Rector und den vollständigen PHP 7.4-Herabstufungsdurchlauf aus.
Befehlsschnittstellen
Abschnitt betitelt „Befehlsschnittstellen“Nutzen Sie diese Tabelle, wenn Sie die genaue Signatur, die Flags und das Exit-Verhalten der Build-Einstiegspunkte und der Skriptklassen benötigen, die einen Build steuern.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Notizen |
|---|---|---|---|---|---|
scripts/build.php | Ziel, Version, Quellpfade, Ausgabepfade und Flags gemäß Skriptdokumentation. | Verwendet branch-spezifische Ziel-Standardwerte. | Erzeugter Paketbaum. | Exit-Code ungleich null und stufenspezifische Fehlerausgabe. | Haupteinstiegspunkt für den Build. Auf einem Build-Host ausführen, nicht in eine Anwendung einbinden. |
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false) | Version, Quellverzeichnis, Ausgabeverzeichnis, Ziellaufzeitspur, Flag für den Einschluss von Pro, Dry-Run-Flag. | PHP 8.1-Ziel; Pro ist eingeschlossen, außer bei PHP 7.4; schreibt, sofern kein Dry-Run aktiviert ist. | Build | InvalidArgumentException bei nicht unterstütztem Ziel; Stufenfehler während run(). | Skriptklasse hinter scripts/build.php. |
Build::run() | keine. | Validiert den Vertrag, führt Quellen zusammen, passt die composer.json-Metadaten an und führt Rector-Durchläufe aus. | bool | Liefert false bei erwarteten Stufenfehlern; kann bei unerwarteten Dateisystem- oder Laufzeitfehlern werfen. | CI sollte bei false fehlschlagen. |
composer build:dry | Composer-Skript-Wrapper. | Build-Validierung im Dry-Run. | Exit-Status und Logs. | Exit-Code ungleich null bei Build- oder Validierungsfehlern. | Wird von CI-Gates verwendet. |
scripts/merge-sources.php | Quell-Checkout-Pfade und Merge-Ziel. | Führt die ausgewählten Quellpakete für die Ziellaufzeit zusammen. | Zusammengeführter Quellbaum. | Fehlende Quelle, nicht unterstütztes Ziel, Dateisystemfehler. | Halten Sie die Quell-Refs am Release-Tag ausgerichtet. |
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false) | Quellbasisverzeichnis, Ausgabeverzeichnis, Flag für den Einschluss von Pro, Dry-Run-Flag, Core-only-Flag. | Führt alle konfigurierten Repos zusammen oder nur Core, wenn coreOnly true ist. | MergeSources | Ungültige Quell- oder Ausgabepfade während des Laufs. | Skriptklasse hinter scripts/merge-sources.php. |
MergeSources::run() | keine. | Kopiert und normalisiert die ausgewählten Quellbäume in das Build-Ziel. | bool | Liefert false bei erwarteten Merge-Fehlern. | Logs lassen sich mit getLog() auslesen. |
MergeSources::getLog() | keine. | Liefert die gesammelten Stufen-Log-Einträge. | array | keine erwartet. | Für CI-Diagnostik verwenden. |
scripts/adjust-composer.php | Metadaten der erzeugten composer.json und Version. | Schreibt Paket-Constraints und Replace-Einträge für die erzeugte Ausgabe. | Angepasste composer.json. | Ungültige Version oder fehlende erzeugte Dateien. | Definiert die Identität des erzeugten Pakets. |
AdjustComposer::__construct(string $version, string $target = 'php81') | Versionsstring und Zielspur. | PHP 8.1-Ziel. | AdjustComposer | Fehler durch ein ungültiges Ziel in den Erzeugungspfaden. | Wird von Build-Skripten und Tests verwendet. |
AdjustComposer::generatePublicComposer() | keine. | Erzeugt Metadaten für nextpdf/backport. | array | keine erwartet. | Reine Erzeugungs-API für Tests. |
AdjustComposer::generateProComposer() | keine. | Erzeugt Metadaten für nextpdf/backport-pro. | array | keine erwartet. | Reine Erzeugungs-API für die proprietäre Build-Spur. |
AdjustComposer::writePublicComposer(string $outputDir) | Ausgabeverzeichnis. | Schreibt die erzeugte öffentliche composer.json. | void | Dateisystemfehler. | Nur in erzeugten Ausgabeverzeichnissen verwenden. |
AdjustComposer::writeProComposer(string $proOutputDir) | Pro-Ausgabeverzeichnis. | Schreibt die erzeugte Pro-composer.json. | void | Dateisystemfehler. | Setzt voraus, dass der Pro-Ausgabebaum existiert. |
ValidateBuildContract::__construct(string $repoRoot) | Repository-Wurzel. | Verwendet die angegebene Repo-Wurzel als Vertragsbasis. | ValidateBuildContract | keine erwartet. | Skriptklasse zur Vertragsvalidierung. |
ValidateBuildContract::run() | keine. | Prüft erforderliche Eingaben und Build-Annahmen. | bool | Liefert false bei Vertragsverletzung. | Ausführen, bevor Sie der Build-Ausgabe vertrauen. |
Rector-Konfiguration
Abschnitt betitelt „Rector-Konfiguration“Verwenden Sie diese Tabelle, wenn Sie wissen müssen, welche Rector-Konfigurationsdatei welche Zielspur steuert und wo jeder Durchlauf in die PHP 8.1-Einzeldurchlauf- oder PHP 7.4-Zweidurchlauf-Pipeline passt.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Notizen |
|---|---|---|---|---|---|
rector/config/rector-php81.php | Quellbaum und Rector-Laufzeit. | Einzeldurchlauf-Herabstufung auf das PHP 8.1-Ziel. | Transformierter Quellcode. | Parse- oder Transformationsfehler von Rector. | Wird für die PHP 8.1-Distributionsspur verwendet. |
rector/config/rector-php74-enums.php | Quellbaum und Rector-Laufzeit. | Erster PHP 7.4-Durchlauf zur Enum-Konvertierung. | Zwischenstand des transformierten Quellcodes. | Parse- oder Transformationsfehler von Rector. | Läuft vor dem vollständigen PHP 7.4-Durchlauf. |
rector/config/rector-php74.php | Zwischenquellcode und Rector-Laufzeit. | Vollständiger PHP 7.4-Herabstufungsdurchlauf. | PHP 7.4-kompatibler Quellcode. | Parse- oder Transformationsfehler von Rector. | Wird für die PHP 7.4-Distributionsspur verwendet. |
Eigene Regeln
Abschnitt betitelt „Eigene Regeln“Nutzen Sie diese Tabelle, wenn Sie die drei projektspezifischen Rector-Regeln pflegen oder erweitern und den Methodenvertrag jeder Regel sowie die Syntax benötigen, die sie transformiert.
| Symbol | Parameter | Standardverhalten | Rückgabe | Wirft oder schlägt fehl mit | Notizen |
|---|---|---|---|---|---|
DowngradeAsymmetricVisibilityRector | Eigenschaften oder beförderte Parameter, die asymmetrische Sichtbarkeit nutzen. | Einfache Sichtbarkeit, kompatibel mit älteren Laufzeiten. | Erhält die Lesesichtbarkeit, wo möglich. | Fehler der Rector-Regel. | Setter-Einschränkungen gelten nur zur Kompilierzeit und werden in der erzeugten Ausgabe entfernt. |
DowngradeAsymmetricVisibilityRector::getRuleDefinition() | keine. | Liefert Rector-Regelmetadaten und Beispiele. | RuleDefinition | keine erwartet. | Hält die Regeldokumentation für das Rector-Tooling sichtbar. |
DowngradeAsymmetricVisibilityRector::getNodeTypes() | keine. | Wählt die von der Regel inspizierten Node-Typen aus. | array<class-string<Node>> | keine erwartet. | Der Geltungsbereich sollte für deterministische Transformationen eng bleiben. |
DowngradeAsymmetricVisibilityRector::refactor(Node $node) | AST-Node. | Konvertiert asymmetrische Sichtbarkeit, wo vorhanden. | `Node | null` | Fehler der Rector-Regel. |
DowngradeCloneWithRector | clone() mit Eigenschaftsüberschreibungen. | Clone mit anschließenden expliziten Eigenschaftszuweisungen. | Verwendet erzeugte temporäre Variablen. | Fehler der Rector-Regel. | Muss nach den Readonly-Property-Herabstufungen laufen. |
DowngradeCloneWithRector::getRuleDefinition() | keine. | Liefert Regelmetadaten und Beispiele. | RuleDefinition | keine erwartet. | Wird von der Rector-Diagnostik verwendet. |
DowngradeCloneWithRector::getNodeTypes() | keine. | Wählt Return- und Ausdrucks-Nodes aus. | array<class-string<Node>> | keine erwartet. | Hält die Regel auf die Clone-with-Syntax fokussiert. |
DowngradeCloneWithRector::refactor(Node $node) | AST-Node. | Schreibt Clone-with in Clone mit anschließenden Zuweisungen um. | `array | null` | Fehler der Rector-Regel. |
DowngradeTraitConstantsRector | Trait-Konstanten und Referenzen darauf. | Statische Eigenschaften und Eigenschaftsreferenzen. | Erhält die Sichtbarkeit, wo möglich. | Fehler der Rector-Regel. | Entfernt final, weil ältere Eigenschaften nicht final sein können. |
DowngradeTraitConstantsRector::getRuleDefinition() | keine. | Liefert Regelmetadaten und Beispiele. | RuleDefinition | keine erwartet. | Wird von der Rector-Diagnostik verwendet. |
DowngradeTraitConstantsRector::getNodeTypes() | keine. | Wählt Trait- und Klassenkonstanten-Fetch-Nodes aus. | array<class-string<Node>> | keine erwartet. | Hält die Regel auf Trait-Konstanten begrenzt. |
DowngradeTraitConstantsRector::refactor(Node $node) | AST-Node. | Schreibt Trait-Konstanten und Referenzen in kompatible Eigenschaften um. | `Node | null` | Fehler der Rector-Regel. |
Vertrag des erzeugten Pakets
Abschnitt betitelt „Vertrag des erzeugten Pakets“Verwenden Sie diese Tabelle, um zu sehen, was der Builder ausgibt: die Paketnamen, die ein nachgelagertes Projekt tatsächlich installiert, und welches Paket die Pro-Distribution bereitstellt.
| Erzeugtes Paket | Laufzeitrolle | Notizen |
|---|---|---|
nextpdf/backport | Erzeugte Open-Source-Laufzeitdistribution. | Ersetzt ausgewählte nextpdf/*-Pakete für die Ziellaufzeit. |
nextpdf/backport-pro | Erzeugte proprietäre Pro-Distribution, wenn Pro-Quellcode vorhanden ist. | Wird getrennt vom Open-Source-Paket veröffentlicht. |
Entwicklungshinweise
Abschnitt betitelt „Entwicklungshinweise“- Der Builder verbraucht Quell-Releases und gibt erzeugte Artefakte aus. Patchen Sie die erzeugte Ausgabe nicht; sie ist nicht die Source of Truth.
- Jede eigene Regel muss Fixture-Tests haben, bevor sie in die Build-Pipeline kommt.
- Release-Jobs müssen die erzeugte Ausgabe auf der Ziellaufzeit validieren, nicht nur auf dem Build-Host.