Démarrage rapide du Backport Builder NextPDF

Outillage de compilation — PAS une dépendance d’exécution. Ce guide pas à pas s’exécute sur un hôte de mainteneur ou d’intégration continue (CI). L’archive produite est celle qu’un projet en aval consomme. Les étapes décrites ici ne s’exécutent jamais sur un serveur d’application.

En un coup d’œil

Tu vas exécuter trois opérations. D’abord, l’essai à blanc, qui vérifie que le pipeline est correctement câblé sans toucher aux fichiers. Ensuite, une compilation PHP 8.1 complète. Puis une compilation PHP 7.4 complète. Chaque étape tient en une seule commande. Chacune s’appuie sur un script Composer ou sur une invocation documentée de scripts/build.php.

Prérequis

Un hôte de compilation avec PHP >=8.4 <9.0 et les dépendances de compilation installées (composer install, sans --no-dev). Voir /integrations/backport/install/.
Les dépôts sources extraits dans des répertoires côte à côte sous une même racine de sources. La compilation PHP 8.1 lit nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter et nextpdf-Pro (pour Pro). La compilation PHP 7.4 ne lit que nextpdf. Vérifié d’après scripts/merge-sources.php.

Étape 1 — essai à blanc

L’essai à blanc exécute chaque étape uniquement en mode rapport. La fusion répertorie ce qu’elle copierait. Rector est annoncé mais n’est pas exécuté. Les étapes de génération du fichier Composer, de copie des ressources et de validation affichent leur intention. Rien n’est écrit. Lance-le d’abord pour confirmer que l’organisation de tes sources et tes options sont correctes, car c’est le contrôle le plus rapide.

composer build:dry

composer build:dry correspond à php scripts/build.php --dry-run. Vérifié d’après composer.jsonscripts et scripts/build.php (la branche dryRun dans chaque étape). Avec les options par défaut, la cible est php81 et la racine des sources reste celle par défaut du script. Tu peux redéfinir l’une comme l’autre, comme le montre l’étape 2.

Si l’essai à blanc signale un dépôt source manquant, il s’arrête immédiatement et indique le dépôt concerné. Corrige l’organisation des sources avant de continuer — voir /integrations/backport/troubleshooting/.

Étape 2 — compilation PHP 8.1 complète

La compilation PHP 8.1 enchaîne plusieurs étapes. Elle fusionne le cœur, les adaptateurs de frameworks et la couche de compatibilité tcpdf. Elle exécute la configuration Rector en passe unique. Elle génère le nextpdf/backportcomposer.json. Elle copie la licence, écrit un CHANGELOG.md et compte les fichiers PHP produits.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

Vérifié d’après le point d’entrée CLI scripts/build.php. Les cinq étapes s’exécutent dans l’ordre : fusionner les sources, exécuter la rétrogradation Rector, générer composer.json, copier les ressources statiques, valider la sortie. Chaque étape affiche une coche en cas de succès. La première étape qui échoue arrête la compilation et affiche son erreur. Pour exclure Pro, ajoute --no-pro.

En cas de succès, l’orchestrateur affiche le temps écoulé et le chemin de sortie. Lorsque Pro est inclus, il affiche aussi le chemin de sortie de Pro. Le répertoire de sortie contient alors src/, tests/, un composer.json généré qui déclare la table de correspondance replace et les exigences de polyfill, LICENSE et CHANGELOG.md.

Étape 3 — compilation PHP 7.4 complète

La compilation PHP 7.4 ne porte que sur le cœur et exécute le pipeline à deux passes. Les passes comprennent le prétraitement des énumérations, un vidage du cache, les correctifs post-Rector, puis la rétrogradation complète.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

Vérifié d’après scripts/build.php. Ici, --target=php74 force le mode cœur seul et désactive Pro, et runRector() sélectionne le chemin à deux passes. Le composer.json généré porte la contrainte >=7.4 <8.1, ne remplace que nextpdf/core, et ajoute les polyfills PHP 8.0 et 8.1 en plus des polyfills 8.2–8.5.

Étape 4 — lire la sortie

L’étape de validation compte les fichiers PHP dans output/src et échoue si ce nombre est nul. Elle ne lance pas de vérification syntaxique locale, car l’interpréteur local est la version moderne de PHP de l’hôte de compilation, pas la cible. Elle affiche la commande Docker permettant de valider dans le véritable environnement d’exécution cible. Vérifié d’après scripts/build.php (validateOutput()).

Pour effectuer une validation complète, lance la vérification de syntaxe sous le PHP cible. Le workflow de publication fait exactement cela. Il contrôle la syntaxe de la sortie sur PHP 8.1 (ou PHP 7.4), puis l’installe et la teste sur toute la matrice de support. Voir /integrations/backport/production-usage/.

Ce que tu as compilé

Artefact	Compilé par	Contrainte	Remplace
`nextpdf/backport` (PHP 8.1)	Étape 2	`>=8.1 <8.5`	core + artisan + laravel + symfony + codeigniter + compat-legacy
`nextpdf/backport-pro` (PHP 8.1)	Étape 2, lorsque Pro est inclus	`>=8.1 <8.5`	`nextpdf/pro`
`nextpdf/backport` (PHP 7.4)	Étape 3	`>=7.4 <8.1`	`nextpdf/core`

Vérifié d’après scripts/adjust-composer.php.

Étapes suivantes

/integrations/backport/production-usage/ — intègre cela au workflow de publication piloté par les événements.
/integrations/backport/configuration/ — la référence des règles et options utilisées par ces commandes.
/integrations/backport/troubleshooting/ — chaque échec d’étape et ce qu’il signifie.