Dépannage du Backport Builder NextPDF

Outil de build — PAS une dépendance d’exécution. Chaque symptôme décrit sur cette page correspond à une condition de build sur l’hôte d’un mainteneur ou de CI. Aucune de ces conditions n’apparaît dans une application en aval.

En bref

Le build exécute cinq étapes dans l’ordre. Il s’arrête à la première défaillance et affiche le nom de l’étape ainsi que le message associé. Lis l’étape, puis retrouve la cause correspondante ci-dessous. Les étapes sont : fusion des sources, rétrogradation Rector, génération de composer.json, copie des ressources statiques et validation de la sortie. Vérifié par rapport à scripts/build.php (run() et step()).

Étape : fusionner les sources

« Source repo '' not found at :  »

La fusion valide chacun des dépôts sources attendus avant la copie. Elle s’interrompt en indiquant le nom et le chemin du dépôt manquant. La cible PHP 8.1 attend nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter et, lorsque Pro est inclus, nextpdf-Pro. La cible PHP 7.4 n’attend que nextpdf. Vérifié par rapport à scripts/merge-sources.php (boucle de validation run(), table des dépôts __construct()).

Résolution : extrais les dépôts sous forme de répertoires frères dans le chemin passé à --source-dir, avec exactement les noms de répertoires ci-dessus. Une exécution à blanc liste chaque dépôt qu’elle lirait. Utilise-la pour vérifier la disposition avant un build complet.

Étape : exécuter la rétrogradation Rector

Rector se termine avec un code non nul

L’orchestrateur signale Rector failed on <label> (exit code: N) et s’arrête. Le libellé indique quelle passe a échoué : public package, pro package, enum pre-processing ou full downgrade. Vérifié par rapport à scripts/build.php (runRectorPass()).

Plantage du résolveur de paramètres par défaut sur les valeurs par défaut d’enum (PHP 7.4)

C’est la raison pour laquelle la cible PHP 7.4 s’exécute en deux passes. Le résolveur des valeurs par défaut des paramètres de Rector plante lorsqu’un cas d’enum est utilisé comme valeur par défaut d’une promotion de constructeur. La passe 1 (rector-php74-enums.php) convertit d’abord les enums en classes regroupant des constantes. La passe complète de la passe 2 ne rencontre alors plus jamais de valeur par défaut de cas d’enum. Si tu contournes l’orchestrateur et exécutes directement la configuration PHP 7.4 complète sur des sources contenant des enums, attends-toi à ce plantage. Vérifié par rapport à scripts/build.php (commentaire runRector() et séquence à deux passes) et rector/config/rector-php74-enums.php.

Les scripts de benchmark font planter Rector

rector-php81.php et rector-php74.php ignorent */tests/Benchmark/*. Ces scripts référencent des bibliothèques PDF externes que Rector ne peut pas résoudre, ce qui fait planter le résolveur des valeurs par défaut des paramètres. Si un chemin de benchmark est traité, c’est que le motif glob d’exclusion est absent ou que le chemin diffère. Vérifié par rapport aux appels withSkip().

Plantage MHASH_XXH* (PHP 7.4)

rector-php74.php ignore DowngradeHashAlgorithmXxHashRector. Cette règle intégrée plante sur les constantes xxHash. La source n’utilise pas xxHash ; l’exclusion ne présente donc pas de risque. Vérifié par rapport à rector/config/rector-php74.php (withSkip()).

Étape : correctifs post-Rector (PHP 7.4 uniquement)

Les correctifs s’exécutent entre les deux passes. Ils réécrivent les motifs laissés par la règle de conversion enum-vers-classe. Si la sortie PHP 7.4 présente une erreur d’analyse impliquant EnumClass::Case->value, ->name, une ancienne méthode d’enum appelée comme méthode d’instance, ou un argument nommé sur un type non résolu, c’est que le correctif n’a pas reconnu ce motif. La limitation du clone-with s’applique également ici : la correspondance des arguments n’est pas récursive, donc une valeur de remplacement contenant des parenthèses imbriquées n’est pas réécrite. Vérifié par rapport à scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) et rector/rules/DowngradeCloneWithRector.php (limitation documentée).

Étape : générer composer.json

Cette étape déplace les répertoires src/ et tests/ traités du répertoire de build temporaire vers le répertoire de sortie. Elle écrit ensuite le composer.json généré. Une défaillance ici est presque toujours liée au système de fichiers : le répertoire de sortie n’est pas accessible en écriture, ou l’arborescence de build temporaire est absente parce que Rector n’a rien produit. Vérifié par rapport à scripts/build.php (adjustComposer(), moveTree()).

Étape : copier les ressources statiques

Cette étape copie LICENSE depuis le dépôt source principal et écrit un CHANGELOG.md généré. Lorsque la licence est absente, la copie est ignorée silencieusement et le build continue ; le changelog est toujours écrit. Une défaillance ici indique que le répertoire de sortie est devenu inaccessible en écriture pendant le build. Vérifié par rapport à scripts/build.php (copyStaticAssets()).

Étape : valider la sortie

« Output src/ directory not found » / « No PHP files found in output »

La validation exige que output/src ne soit pas vide. Une arborescence vide signifie que la fusion n’a rien copié ou que le déplacement des fichiers a échoué. Vérifié par rapport à scripts/build.php (validateOutput()).

« Syntax validation : skipped (requires PHP runtime) »

C’est le comportement attendu, pas une erreur. L’hôte de build exécute une version moderne de PHP, pas la cible ; l’étape locale se limite donc à compter les fichiers et à afficher la commande Docker pour une véritable vérification de syntaxe. Le contrôle de syntaxe de référence est l’étape php -l post-build du workflow de release, exécutée dans l’environnement d’exécution cible réel. Vérifié par rapport à scripts/build.php (validateOutput()) et .github/workflows/build.yml (les étapes de vérification de syntaxe PHP 8.1 / PHP 7.4).

Limites connues

Elles découlent de l’approche de rétrogradation. Elles sont vérifiées par rapport aux règles et à la section « Known Limitations » du README.md du projet :

• Les propriétés readonly sont supprimées. readonly est retiré afin que l’affectation explicite de propriété produite par l’expansion du clone-with soit légale dans l’environnement d’exécution plus ancien. L’immuabilité n’est plus imposée par l’environnement d’exécution dans la sortie rétrogradée.
• #[Override] n’est pas imposé sur PHP 8.1. L’attribut peut subsister, mais l’environnement d’exécution plus ancien l’ignore.
• La cible PHP 7.4 est réservée au cœur. Les adaptateurs de framework, la couche de compatibilité tcpdf et Pro ne font pas partie de la distribution PHP 7.4, par conception du script de build.
• Pro est un paquet distinct et réservé à PHP 8.1. Il n’existe pas de build Pro pour PHP 7.4.
• La correspondance des arguments du clone-with n’est pas récursive. Les valeurs de remplacement contenant des parenthèses imbriquées ne sont pas transformées, et seules les clés de tableau de type chaîne sont résolues en noms de propriété.

Étapes suivantes

• /integrations/backport/configuration/ — la référence des règles et des drapeaux.
• /integrations/backport/production-usage/ — les contrôles CI et les voies de release.