API-referentie voor Backport Builder
In een oogopslag
Sectie met titel “In een oogopslag”De Backport Builder is een buildtool, geen runtimebibliotheek. De publieke interface bestaat uit de reeks buildopdrachten (scripts/build.php en de bijbehorende composer build*-wrappers), de vier onderliggende scriptklassen (Build, MergeSources, AdjustComposer, ValidateBuildContract), de drie Rector-configuratiebestanden, de drie aangepaste Rector-regels en het gegenereerde pakketcontract (nextpdf/backport en nextpdf/backport-pro). Voer deze uit op een buildhost of continuous-integration-host (CI) om moderne NextPDF-broncode om te zetten in een gedowngrade distributie. Neem deze nooit op in een applicatie.
Als je nieuw bent, begin je met composer build:dry (wat verwijst naar php scripts/build.php --dry-run). Die opdracht doorloopt elke fase in rapportagemodus zonder bestanden te schrijven, zodat je de bronindeling en de vlaggen kunt controleren vóór een echte build. Het eerste voorbeeld onder ‘Veelvoorkomende taken’ toont dezelfde opdracht.
Veelvoorkomende taken
Sectie met titel “Veelvoorkomende taken”Je gebruikt dit pakket meestal om builds uit te voeren op een buildhost. Elk voorbeeld hieronder is een enkele opdracht, geverifieerd aan de hand van scripts/build.php en composer.json.
Valideer de pijplijn zonder iets te schrijven (de veilige eerste run):
composer build:dryDit verwijst naar php scripts/build.php --dry-run. Het voert samenvoeging, Rector, composer-generatie, asset-kopie en validatie uit in rapportagemodus, zonder iets te kopiëren.
Genereer de volledige PHP 8.1-distributie (nextpdf/backport, plus nextpdf/backport-pro wanneer Pro-broncode aanwezig is):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./outputDit voegt de core, de framework-adapters en de tcpdf-compatibiliteitslaag samen. Het voert de enkele Rector-doorloop uit voor het PHP 8.1-doel en schrijft de gegenereerde pakketboom naar ./output. Voeg --no-pro toe om het Pro-pakket over te slaan.
Genereer de core-only PHP 7.4-distributie (de tweeledige enum-pijplijn):
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./output-php74 \ --target=php74--target=php74 dwingt core-only-uitvoer af, schakelt Pro uit en voert enum-voorverwerking, post-Rector-correcties en de volledige PHP 7.4-downgradedoorloop uit.
Opdrachtinterfaces
Sectie met titel “Opdrachtinterfaces”Gebruik deze tabel wanneer je exacte signatures, vlaggen en exitgedrag nodig hebt voor de build-entrypoints en de scriptklassen die een build aansturen.
| Symbool | Parameters | Standaardgedrag | Retourneert | Werpt of mislukt met | Opmerkingen |
|---|---|---|---|---|---|
scripts/build.php | Doel, versie, bronpaden, uitvoerpaden en vlaggen zoals het script die documenteert. | Gebruikt branch-specifieke standaarddoelen. | Gegenereerde pakketboom. | Exitcode ongelijk aan nul en fasespecifieke foutuitvoer. | Hoofdentrypoint voor builds. Voer dit uit op een buildhost, niet in een applicatie. |
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false) | Versie, bronmap, uitvoermap, runtime-doellijn, vlag om Pro op te nemen, dry-run-vlag. | Richt zich op PHP 8.1, neemt Pro op behalve voor PHP 7.4, en schrijft tenzij dry-run is ingeschakeld. | Build | InvalidArgumentException bij een niet-ondersteund doel; fasefouten tijdens run(). | Scriptklasse achter scripts/build.php. |
Build::run() | Geen. | Valideert het contract, voegt bronnen samen, past de composer.json-metadata aan en voert Rector-doorlopen uit. | bool | Retourneert false bij verwachte fasefouten; kan een uitzondering werpen bij onverwachte bestandssysteem- of runtimefouten. | CI moet falen bij false. |
composer build:dry | Composer-scriptwrapper. | Buildvalidatie in dry-run-modus. | Exitstatus en logs. | Exitcode ongelijk aan nul bij een build- of validatiefout. | Gebruikt door CI-gates. |
scripts/merge-sources.php | Paden naar bron-checkouts en samenvoegdoel. | Voegt geselecteerde bronpakketten samen voor de doelruntime. | Samengevoegde bronboom. | Ontbrekende bron, niet-ondersteund doel, bestandssysteemfout. | Houd de bronreferenties afgestemd op de release-tag. |
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false) | Bronbasismap, uitvoermap, vlag om Pro op te nemen, dry-run-vlag, core-only-vlag. | Voegt alle geconfigureerde repository’s samen, of alleen de core als coreOnly true is. | MergeSources | Ongeldige bron- of uitvoerpaden tijdens de run. | Scriptklasse achter scripts/merge-sources.php. |
MergeSources::run() | Geen. | Kopieert en normaliseert geselecteerde bronbomen naar het builddoel. | bool | Retourneert false bij verwachte samenvoegfouten. | Logs kunnen worden gelezen met getLog(). |
MergeSources::getLog() | Geen. | Retourneert de verzamelde fase-logvermeldingen. | array | Geen verwacht. | Gebruik voor CI-diagnostiek. |
scripts/adjust-composer.php | Gegenereerde composer.json-metadata en -versie. | Schrijft pakketbeperkingen en replace-vermeldingen voor de gegenereerde uitvoer. | Aangepaste composer.json. | Ongeldige versie of ontbrekende gegenereerde bestanden. | Beheert de identiteit van het gegenereerde pakket. |
AdjustComposer::__construct(string $version, string $target = 'php81') | Versietekenreeks en doellijn. | PHP 8.1-doel. | AdjustComposer | Fouten door ongeldige doelen in de generatiepaden. | Gebruikt door buildscripts en tests. |
AdjustComposer::generatePublicComposer() | Geen. | Produceert metadata voor nextpdf/backport. | array | Geen verwacht. | Pure generatie-API voor tests. |
AdjustComposer::generateProComposer() | Geen. | Produceert metadata voor nextpdf/backport-pro. | array | Geen verwacht. | Pure generatie-API voor de propriëtaire buildlijn. |
AdjustComposer::writePublicComposer(string $outputDir) | Uitvoermap. | Schrijft de gegenereerde publieke composer.json. | void | Bestandssysteemfouten. | Gebruik uitsluitend in gegenereerde uitvoermappen. |
AdjustComposer::writeProComposer(string $proOutputDir) | Pro-uitvoermap. | Schrijft de gegenereerde Pro-composer.json. | void | Bestandssysteemfouten. | Vereist dat de Pro-uitvoerboom bestaat. |
ValidateBuildContract::__construct(string $repoRoot) | Repository-root. | Gebruikt de opgegeven repository-root als contractbasis. | ValidateBuildContract | Geen verwacht. | Contractvalidator op scriptniveau. |
ValidateBuildContract::run() | Geen. | Controleert de vereiste invoer en buildaannames. | bool | Retourneert false bij een contractfout. | Voer dit uit voordat je de builduitvoer vertrouwt. |
Rector-configuratie
Sectie met titel “Rector-configuratie”Gebruik deze tabel om te zien welk Rector-configuratiebestand elke doellijn aanstuurt en waar elke doorloop past in de PHP 8.1-pijplijn met één doorloop of de PHP 7.4-pijplijn met twee doorlopen.
| Symbool | Parameters | Standaardgedrag | Retourneert | Werpt of mislukt met | Opmerkingen |
|---|---|---|---|---|---|
rector/config/rector-php81.php | Bronboom en Rector-runtime. | Downgrade met één doorloop naar het PHP 8.1-doel. | Getransformeerde broncode. | Rector-parseer- of transformatiefout. | Gebruikt voor de PHP 8.1-distributielijn. |
rector/config/rector-php74-enums.php | Bronboom en Rector-runtime. | Eerste PHP 7.4-doorloop voor enum-conversie. | Tussenliggende, getransformeerde broncode. | Rector-parseer- of transformatiefout. | Wordt uitgevoerd vóór de volledige PHP 7.4-doorloop. |
rector/config/rector-php74.php | Tussenliggende broncode en Rector-runtime. | Volledige PHP 7.4-downgradedoorloop. | PHP 7.4-compatibele broncode. | Rector-parseer- of transformatiefout. | Gebruikt voor de PHP 7.4-distributielijn. |
Aangepaste regels
Sectie met titel “Aangepaste regels”Gebruik deze tabel wanneer je de drie projectspecifieke Rector-regels onderhoudt of uitbreidt en het methodecontract van elke regel plus de syntaxis die deze transformeert nodig hebt.
| Symbool | Parameters | Standaardgedrag | Retourneert | Werpt of mislukt met | Opmerkingen |
|---|---|---|---|---|---|
DowngradeAsymmetricVisibilityRector | Eigenschappen of gepromoveerde parameters die asymmetrische zichtbaarheid gebruiken. | Eenvoudige zichtbaarheid die compatibel is met oudere runtimes. | Behoudt waar mogelijk de leeszichtbaarheid. | Fout in Rector-regel. | Setterbeperkingen gelden alleen tijdens het compileren en worden in de gegenereerde uitvoer verwijderd. |
DowngradeAsymmetricVisibilityRector::getRuleDefinition() | Geen. | Retourneert metadata en voorbeelden voor de Rector-regel. | RuleDefinition | Geen verwacht. | Houdt de regeldocumentatie zichtbaar voor het Rector-gereedschap. |
DowngradeAsymmetricVisibilityRector::getNodeTypes() | Geen. | Selecteert de knooppunttypen die door de regel worden geïnspecteerd. | array<class-string<Node>> | Geen verwacht. | De reikwijdte moet beperkt blijven voor deterministische transformaties. |
DowngradeAsymmetricVisibilityRector::refactor(Node $node) | AST-knooppunt. | Converteert asymmetrische zichtbaarheid als die aanwezig is. | `Node | null` | Fout in Rector-regel. |
DowngradeCloneWithRector | clone() met eigenschapsoverschrijvingen. | Clone plus expliciete eigenschapstoewijzingen. | Gebruikt gegenereerde tijdelijke variabelen. | Fout in Rector-regel. | Moet worden uitgevoerd na readonly-eigenschapsdowngrades. |
DowngradeCloneWithRector::getRuleDefinition() | Geen. | Retourneert regelmetadata en voorbeelden. | RuleDefinition | Geen verwacht. | Gebruikt door Rector-diagnostiek. |
DowngradeCloneWithRector::getNodeTypes() | Geen. | Selecteert return- en expressieknooppunten. | array<class-string<Node>> | Geen verwacht. | Houdt de regel gericht op clone-with-syntaxis. |
DowngradeCloneWithRector::refactor(Node $node) | AST-knooppunt. | Herschrijft clone-with naar clone plus toewijzingen. | `array | null` | Fout in Rector-regel. |
DowngradeTraitConstantsRector | Trait-constanten en verwijzingen daarnaar. | Statische eigenschappen en eigenschapsverwijzingen. | Behoudt waar mogelijk de zichtbaarheid. | Fout in Rector-regel. | Verwijdert final omdat oudere eigenschappen niet final kunnen zijn. |
DowngradeTraitConstantsRector::getRuleDefinition() | Geen. | Retourneert regelmetadata en voorbeelden. | RuleDefinition | Geen verwacht. | Gebruikt door Rector-diagnostiek. |
DowngradeTraitConstantsRector::getNodeTypes() | Geen. | Selecteert trait- en class-constant-fetch-knooppunten. | array<class-string<Node>> | Geen verwacht. | Houdt de regel beperkt tot trait-constanten. |
DowngradeTraitConstantsRector::refactor(Node $node) | AST-knooppunt. | Herschrijft trait-constanten en verwijzingen daarnaar naar compatibele eigenschappen. | `Node | null` | Fout in Rector-regel. |
Gegenereerd pakketcontract
Sectie met titel “Gegenereerd pakketcontract”Gebruik deze tabel om te zien wat de builder genereert: de pakketnamen die downstream-projecten installeren en het pakket dat de Pro-distributie bevat.
| Geproduceerd pakket | Runtimerol | Opmerkingen |
|---|---|---|
nextpdf/backport | Gegenereerde opensource-runtimedistributie. | Vervangt geselecteerde nextpdf/*-pakketten voor de doel-runtime. |
nextpdf/backport-pro | Gegenereerde propriëtaire Pro-distributie wanneer Pro-broncode aanwezig is. | Wordt afzonderlijk van het opensourcepakket gepubliceerd. |
Ontwikkelnotities
Sectie met titel “Ontwikkelnotities”- De builder gebruikt bronreleases en genereert artefacten. Pas de gegenereerde uitvoer niet aan alsof die de bron van waarheid is.
- Elke aangepaste regel moet fixturetests hebben voordat die in de buildpijplijn wordt opgenomen.
- Releasejobs moeten de gegenereerde uitvoer valideren op de doel-runtime, niet alleen op de buildhost.