Problemen oplossen voor de NextPDF Backport Builder

Buildtool — GEEN runtime-afhankelijkheid. Elk symptoom op deze pagina is een voorwaarde tijdens buildtijd op een maintainer-host of een continuous-integration-host (CI). Geen van deze voorwaarden treedt op in een downstreamtoepassing.

In één oogopslag

De build doorloopt vijf fasen in een vaste volgorde. De build stopt bij de eerste fout en toont de fasenaam en het bijbehorende bericht. Gebruik de fasenaam om hieronder de bijbehorende oorzaak op te zoeken. De fasen zijn: bronnen samenvoegen, Rector-downgrade uitvoeren, composer.json genereren, statische assets kopiëren en uitvoer valideren. Geverifieerd aan de hand van scripts/build.php (run() en step()).

Fase: bronnen samenvoegen

”Source repo '' not found at: ”

De samenvoeging valideert elke verwachte bronrepository voordat er bestanden worden gekopieerd. Als een repository ontbreekt, breekt de build af en toont de naam en het pad van die repository. Het PHP 8.1-target verwacht nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter en — wanneer Pro is inbegrepen — nextpdf-Pro. Het PHP 7.4-target verwacht alleen nextpdf. Geverifieerd aan de hand van scripts/merge-sources.php (validatielus van run(), repositorymap van __construct()).

Oplossing: check de repositories uit naar naast elkaar liggende mappen onder het pad dat aan --source-dir wordt doorgegeven en gebruik exact de hierboven vermelde mapnamen. Een proefuitvoering toont elke repository die zou worden gelezen. Gebruik die om de structuur te controleren voordat je een volledige build uitvoert.

Fase: Rector-downgrade uitvoeren

Rector eindigt met een niet-nul afsluitcode

De orchestrator meldt Rector failed on <label> (exit code: N) en stopt. Het label geeft aan welke fase is mislukt: public package, pro package, enum pre-processing of full downgrade. Geverifieerd aan de hand van scripts/build.php (runRectorPass()).

Crash van de standaardparameter-resolver bij enum-standaardwaarden (PHP 7.4)

Het PHP 7.4-target gebruikt daarom twee passes. De resolver voor standaardparameterwaarden van Rector crasht wanneer een enum-case wordt gebruikt als standaardwaarde bij constructor-promotion. Pass 1 (rector-php74-enums.php) zet enums eerst om naar klassen met constantenlijsten. De volledige pass in Pass 2 ziet vervolgens nooit een enum-case als standaardwaarde. Als je de orchestrator omzeilt en de volledige PHP 7.4-configuratie rechtstreeks uitvoert op broncode met enums, kun je deze crash verwachten. Geverifieerd aan de hand van scripts/build.php (de opmerking bij runRector() en de tweepass-sequentie) en rector/config/rector-php74-enums.php.

Benchmarkscripts laten Rector crashen

rector-php81.php en rector-php74.php slaan */tests/Benchmark/* over. Die scripts verwijzen naar externe Portable Document Format (PDF)-bibliotheken die Rector niet kan resolven, waardoor de standaardparameter-resolver crasht. Als een benchmarkpad toch wordt verwerkt, ontbreekt de skip-glob of wijkt het pad af. Geverifieerd aan de hand van de withSkip()-aanroepen.

MHASH_XXH*-crash (PHP 7.4)

rector-php74.php slaat DowngradeHashAlgorithmXxHashRector over. Deze ingebouwde regel crasht op de xxHash-constanten. De broncode gebruikt geen xxHash, dus het overslaan is veilig. Geverifieerd aan de hand van rector/config/rector-php74.php (withSkip()).

Fase: correcties na Rector (alleen PHP 7.4)

De correcties worden tussen de twee passes uitgevoerd. Ze herschrijven patronen die de enum-naar-klasse-regel heeft achtergelaten. Als de PHP 7.4-uitvoer een parsefout bevat rond EnumClass::Case->value, ->name, een voormalige enum-methode die als instantiemethode wordt aangeroepen, of een benoemd argument op een onopgelost type, dan hebben de correcties dat patroon niet herkend. De clone-with-beperking geldt hier ook: het matchen van argumenten is niet recursief, dus een overschrijfwaarde met geneste haakjes wordt niet herschreven. Geverifieerd aan de hand van scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) en rector/rules/DowngradeCloneWithRector.php (gedocumenteerde beperking).

Fase: composer.json genereren

Deze fase verplaatst de verwerkte mappen src/ en tests/ van de build-tempmap naar de uitvoermap. Vervolgens schrijft de fase de gegenereerde composer.json weg. Een fout hier wijst vrijwel altijd op een voorwaarde in het bestandssysteem: de uitvoermap is niet beschrijfbaar, of de build-tempboom ontbreekt omdat Rector niets heeft geproduceerd. Geverifieerd aan de hand van scripts/build.php (adjustComposer(), moveTree()).

Fase: statische assets kopiëren

Deze fase kopieert LICENSE uit de core-bronrepository en schrijft een gegenereerde CHANGELOG.md weg. Als LICENSE ontbreekt, wordt het kopiëren stilzwijgend overgeslagen en gaat de build door; de changelog wordt altijd weggeschreven. Een fout hier betekent dat de uitvoermap halverwege de build onbeschrijfbaar is geworden. Geverifieerd aan de hand van scripts/build.php (copyStaticAssets()).

Fase: uitvoer valideren

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

Validatie vereist een niet-lege output/src. Een lege boom betekent dat de samenvoeging niets heeft gekopieerd of dat het verplaatsen van bestanden is mislukt. Geverifieerd aan de hand van scripts/build.php (validateOutput()).

”Syntax validation: skipped (requires PHP runtime)”

Dit is verwacht gedrag, geen fout. De buildhost draait een moderne PHP-versie en niet de target-runtime; daarom telt de lokale fase alleen bestanden en toont deze het Docker-commando voor een echte syntaxcontrole. De doorslaggevende syntaxcontrole is de php -l-stap na de build in de release-workflow, die onder de daadwerkelijke target-runtime draait. Geverifieerd aan de hand van scripts/build.php (validateOutput()) en .github/workflows/build.yml (de syntaxcontrolestappen voor PHP 8.1 / PHP 7.4).

Bekende beperkingen

Deze beperkingen zijn inherent aan de downgrade-aanpak. Ze zijn geverifieerd aan de hand van de regels en het gedeelte ‘Known Limitations’ in de README.md van het project:

• Readonly-eigenschappen worden verwijderd. De build verwijdert readonly zodat de clone-with-expansie eigenschappen expliciet kan toewijzen in de oudere runtime. De gedowngradede uitvoer heeft geen door de runtime afgedwongen onveranderlijkheid meer.
• #[Override] wordt op PHP 8.1 niet afgedwongen. Het attribuut mag blijven staan, maar de oudere runtime doet er niets mee.
• Het PHP 7.4-target omvat alleen de core. Framework-adapters, de tcpdf-compatibiliteitslaag en Pro zijn door de opzet van het buildscript uitgesloten van de PHP 7.4-distributie.
• Pro is een afzonderlijk pakket en alleen voor PHP 8.1. Er is geen Pro-build voor PHP 7.4.
• Het matchen van clone-with-argumenten is niet recursief. Overschrijfwaarden met geneste haakjes worden niet getransformeerd, en alleen array-sleutels van het type string worden herleid tot eigenschapsnamen.

Volgende

• /integrations/backport/configuration/ — de referentie voor regels en vlaggen.
• /integrations/backport/production-usage/ — de CI-gate en de release-lanes.