Amorçage et découverte du backport NextPDF

Outil de build — PAS une dépendance d’exécution. Ce document décrit l’amorçage du builder sur un hôte de mainteneur ou de CI. Les applications en aval ne chargent jamais ce code.

En un coup d’œil

Le builder n’a pas de framework, pas de conteneur d’injection de dépendances ni de découverte automatique de fournisseurs de services. C’est un ensemble de scripts PHP CLI reliés par require_once et par l’autoloader PSR-4 de Composer. Ici, « découverte » recouvre deux réalités concrètes : les dépôts source lus par l’étape de fusion, et la manière dont l’orchestrateur sélectionne la configuration Rector pour la cible.

Vue d’ensemble du pipeline de build

L’orchestrateur est scripts/build.php. Il s’amorce, puis exécute cinq étapes ordonnées. Chaque étape est contrôlée, de sorte que la première défaillance arrête le build :

1. Fusionner les sources — copier les dépôts source dans une seule arborescence.
2. Exécuter le downgrade Rector — passe unique pour PHP 8.1 ; deux passes, plus des corrections, pour PHP 7.4.
3. Générer composer.json — écrire le manifeste du paquet produit avec sa carte replace.
4. Copier les ressources statiques — la licence et un changelog généré.
5. Valider la sortie — compter les fichiers PHP émis ; la vérification de syntaxe faisant foi s’exécute plus tard dans la CI.

Vérifié d’après scripts/build.php (run(), step()). Le détail de la sélection des règles se trouve dans /integrations/backport/configuration/ ; le contrôle de CI se trouve dans /integrations/backport/production-usage/.

Découverte des modules source

La découverte des sources n’est pas pilotée par un manifeste. Elle repose sur une carte fixe dans scripts/merge-sources.php, indexée par nom de dépôt et sélectionnée par la cible.

Pour la cible PHP 8.1, la carte comprend nextpdf (le cœur), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter, et nextpdf-Pro lorsque Pro est inclus. Pour la cible PHP 7.4, la carte se limite à nextpdf. Chaque dépôt est résolu comme un répertoire frère sous la racine --source-dir. Chaque dépôt attendu est validé avant toute copie, et un dépôt manquant interrompt la fusion en indiquant son nom et son chemin. Vérifié d’après scripts/merge-sources.php (MergeSources::__construct(), run()).

La fusion place le cœur dans src/ et chaque adaptateur dans le sous-répertoire correspondant à son espace de noms (src/Artisan/, src/Laravel/, et ainsi de suite). Pro est placé dans une arborescence pro/src/ distincte afin de pouvoir être émis comme son propre paquet. Vérifié d’après MergeSources (mergeCore(), mergeArtisan(), mergePro()).

Séquence d’amorçage

1. scripts/build.php est invoqué sous la SAPI CLI. Il charge merge-sources.php et adjust-composer.php avec require_once.
2. Le point d’entrée CLI lit les options avec getopt() — --version, --source-dir, --output-dir, --target, --dry-run, --no-pro.
3. Une instance Build est construite. Le constructeur valide --target par rapport à ['php74', 'php81'] et lève InvalidArgumentException en cas de valeur invalide, avant que le moindre travail ne commence. Pour la cible PHP 7.4, il force le mode cœur uniquement et désactive Pro.
4. Build::run() exécute les cinq étapes et se termine avec le statut 0 en cas de succès, ou avec le statut 1 à la première défaillance.

Vérifié d’après scripts/build.php (point d’entrée CLI, Build::__construct(), run()).

Liaisons du conteneur

Sans objet. Le builder est un outil CLI sans conteneur d’injection de dépendances ni conteneur de services de framework. Le câblage repose sur des require_once explicites, ainsi que sur l’autoloading PSR-4 de Composer pour NextPDF\Backport\ (les règles) et NextPDF\Backport\Scripts\ (les scripts). Vérifié d’après composer.jsonautoload et les instructions require_once dans scripts/build.php.

Ordre de résolution de la configuration

Il n’y a pas de fichier de configuration. La configuration correspond à l’ensemble des drapeaux CLI, résolus par rapport aux valeurs par défaut intégrées dans le script :

1. Le drapeau CLI, s’il est fourni.
2. La valeur par défaut définie dans le bloc d’analyse getopt() (par exemple, la cible vaut par défaut php81, la version 2.0.0).
3. Le comportement que le constructeur dérive de la cible (PHP 7.4 force le mode cœur uniquement et désactive Pro, quel que soit --no-pro).

Vérifié d’après scripts/build.php (point d’entrée CLI et Build::__construct()). La référence complète des drapeaux se trouve dans /integrations/backport/configuration/.

Diagnostics

L’orchestrateur fournit lui-même la surface de diagnostic. Lance un essai à blanc (composer build:dry) pour afficher, sans rien écrire, les dépôts source qui seraient lus et l’intention de chaque étape. Chaque étape affiche une coche de réussite ou une défaillance nommée. Il n’y a pas de sous-commande de diagnostic distincte ni de point d’entrée bin/. Le builder est invoqué via scripts/build.php ou ses alias de script Composer. Vérifié d’après scripts/build.php (step(), les branches dryRun), scripts/merge-sources.php (le chemin d’essai à blanc de run()), et composer.jsonscripts.

Voir aussi

• /integrations/backport/overview/ — ce qu’est le builder et ce qu’il produit.
• /integrations/backport/integration/ — le contrat d’intégration côté hôte de build.
• /integrations/backport/configuration/ — les configurations de Rector et la référence des drapeaux.
• /integrations/backport/troubleshooting/ — la référence des défaillances étape par étape.