Référence API du Backport Builder
Le Backport Builder est un outil de build, et non une bibliothèque d’exécution. Son interface publique correspond aux commandes de build (scripts/build.php et ses wrappers composer build*), aux quatre classes de niveau script qui pilotent ce processus (Build, MergeSources, AdjustComposer, ValidateBuildContract), aux trois fichiers de configuration Rector, aux trois règles Rector personnalisées et au contrat de package généré (nextpdf/backport et nextpdf/backport-pro). Tu l’exécutes sur un hôte de build ou de CI pour transformer le code source NextPDF moderne en distribution rétrogradée. Tu ne l’ajoutes jamais à une application.
Commence ici : si tu débutes, exécute composer build:dry (qui se résout en php scripts/build.php --dry-run). Il parcourt chaque étape en mode rapport uniquement, sans écrire de fichiers, pour que tu puisses confirmer la disposition des sources et les options avant de lancer un vrai build. Le premier exemple « Common tasks » ci-dessous montre exactement ce flux.
Tâches courantes
Section intitulée « Tâches courantes »Avec ce package, tu lanceras le plus souvent des builds sur un hôte dédié. Chaque exemple ci-dessous est une commande unique, vérifiée à la source dans scripts/build.php et composer.json.
Valide le pipeline sans rien écrire (le premier passage sûr) :
composer build:dryCette commande se résout en php scripts/build.php --dry-run : elle exécute la fusion, Rector, la génération du composer, la copie des assets et la validation en mode rapport uniquement, et ne copie rien.
Produis la distribution PHP 8.1 complète (nextpdf/backport, plus nextpdf/backport-pro lorsque les sources Pro sont présentes) :
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./outputFusionne le core, les adaptateurs de framework et la couche de compatibilité tcpdf, exécute la passe Rector unique pour la cible PHP 8.1 et écrit l’arborescence du package généré dans ./output. Ajoute --no-pro pour ignorer le package Pro.
Produis la distribution PHP 7.4 core uniquement (le pipeline d’énumérations à deux passes) :
php scripts/build.php \ --version=2.0.0 \ --source-dir=/path/to/sources \ --output-dir=./output-php74 \ --target=php74Avec --target=php74, la sortie est limitée au core et Pro est désactivé ; le pipeline exécute ensuite le prétraitement des énumérations, les corrections post-Rector et la passe complète de rétrogradation vers PHP 7.4.
Surfaces de commande
Section intitulée « Surfaces de commande »Reporte-toi à ce tableau quand tu as besoin de la signature exacte, des options et du comportement de sortie des points d’entrée de build et des classes de niveau script qui orchestrent un build.
| Symbole | Paramètres | Comportement par défaut | Renvoie | Lève ou échoue avec | Notes |
|---|---|---|---|---|---|
scripts/build.php | Cible, version, chemins source, chemins de sortie et options documentés par le script. | Utilise les cibles par défaut propres à la branche. | Arborescence du package généré. | Sortie non nulle et message d’erreur propre à l’étape. | Point d’entrée principal du build. À exécuter sur un hôte de build, pas dans une application. |
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false) | Version, répertoire source, répertoire de sortie, voie d’exécution cible, indicateur d’inclusion de Pro, indicateur de dry-run. | Cible PHP 8.1, Pro inclus sauf pour PHP 7.4, écriture effective sauf si le dry-run est activé. | Build | InvalidArgumentException pour une cible non prise en charge ; erreurs d’étape pendant run(). | Classe de niveau script derrière scripts/build.php. |
Build::run() | aucun. | Valide le contrat, fusionne les sources, ajuste les métadonnées de composer.json et exécute les passes Rector. | bool | Renvoie false pour les échecs d’étape attendus ; peut lever une exception pour des erreurs filesystem/runtime inattendues. | La CI doit considérer false comme un échec. |
composer build:dry | Wrapper de script Composer. | Validation de build en dry-run. | Statut de sortie et logs. | Sortie non nulle en cas d’échec de build ou de validation. | Utilisé par les gates de CI. |
scripts/merge-sources.php | Chemins des checkouts source et cible de fusion. | Fusionne les packages source sélectionnés pour l’exécution cible. | Arborescence des sources fusionnées. | Source manquante, cible non prise en charge, échec du filesystem. | Garde les références source alignées sur le tag de release. |
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false) | Répertoire de base des sources, répertoire de sortie, indicateur d’inclusion de Pro, indicateur de dry-run, indicateur core uniquement. | Fusionne tous les dépôts configurés, ou uniquement le core lorsque coreOnly vaut true. | MergeSources | Chemins source ou de sortie invalides pendant l’exécution. | Classe de niveau script derrière scripts/merge-sources.php. |
MergeSources::run() | aucun. | Copie et normalise les arborescences source sélectionnées dans la cible de build. | bool | Renvoie false pour les échecs de fusion attendus. | Les logs peuvent être lus avec getLog(). |
MergeSources::getLog() | aucun. | Renvoie les entrées de log accumulées par étape. | array | aucun attendu. | À utiliser pour le diagnostic de CI. |
scripts/adjust-composer.php | Métadonnées et version du composer.json généré. | Écrit les contraintes de package et les entrées replace pour la sortie générée. | Le composer.json ajusté. | Version invalide ou fichiers générés manquants. | Détient l’identité du package généré. |
AdjustComposer::__construct(string $version, string $target = 'php81') | Chaîne de version et voie cible. | Cible PHP 8.1. | AdjustComposer | Erreurs liées à une cible invalide dans les chemins de génération. | Utilisé par les scripts de build et les tests. |
AdjustComposer::generatePublicComposer() | aucun. | Produit les métadonnées pour nextpdf/backport. | array | aucun attendu. | API de génération pure pour les tests. |
AdjustComposer::generateProComposer() | aucun. | Produit les métadonnées pour nextpdf/backport-pro. | array | aucun attendu. | API de génération pure pour la voie de build propriétaire. |
AdjustComposer::writePublicComposer(string $outputDir) | Répertoire de sortie. | Écrit le composer.json public généré. | void | Erreurs du filesystem. | À utiliser uniquement dans les répertoires de sortie générés. |
AdjustComposer::writeProComposer(string $proOutputDir) | Répertoire de sortie Pro. | Écrit le composer.json Pro généré. | void | Erreurs du filesystem. | Requiert que l’arborescence de sortie Pro existe. |
ValidateBuildContract::__construct(string $repoRoot) | Racine du dépôt. | Utilise la racine du dépôt fournie comme base de contrat. | ValidateBuildContract | aucun attendu. | Validateur de contrat de niveau script. |
ValidateBuildContract::run() | aucun. | Vérifie les entrées requises et les hypothèses de build. | bool | Renvoie false en cas d’échec du contrat. | À exécuter avant de faire confiance à la sortie du build. |
Configuration Rector
Section intitulée « Configuration Rector »Utilise ce tableau pour savoir quel fichier de configuration Rector pilote quelle voie cible et où chaque passe s’insère dans le pipeline à passe unique PHP 8.1 ou à deux passes PHP 7.4.
| Symbole | Paramètres | Comportement par défaut | Renvoie | Lève ou échoue avec | Notes |
|---|---|---|---|---|---|
rector/config/rector-php81.php | Arborescence source et runtime Rector. | Rétrogradation en une seule passe vers la cible PHP 8.1. | Source transformée. | Échec d’analyse ou de transformation Rector. | Utilisé pour la voie de distribution PHP 8.1. |
rector/config/rector-php74-enums.php | Arborescence source et runtime Rector. | Première passe PHP 7.4 pour la conversion des énumérations. | Source transformée intermédiaire. | Échec d’analyse ou de transformation Rector. | S’exécute avant la passe complète PHP 7.4. |
rector/config/rector-php74.php | Source intermédiaire et runtime Rector. | Passe complète de rétrogradation vers PHP 7.4. | Source compatible PHP 7.4. | Échec d’analyse ou de transformation Rector. | Utilisé pour la voie de distribution PHP 7.4. |
Règles personnalisées
Section intitulée « Règles personnalisées »Reporte-toi à ce tableau lorsque tu maintiens ou étends les trois règles Rector propres au projet et que tu as besoin du contrat de méthode de chaque règle et de la syntaxe qu’elle transforme.
| Symbole | Paramètres | Comportement par défaut | Renvoie | Lève ou échoue avec | Notes |
|---|---|---|---|---|---|
DowngradeAsymmetricVisibilityRector | Propriétés ou paramètres promus utilisant une visibilité asymétrique. | Visibilité simple compatible avec les runtimes plus anciens. | Préserve la visibilité en lecture lorsque c’est possible. | Échec de règle Rector. | Les restrictions de setter ne s’appliquent qu’à la compilation et sont supprimées dans la sortie générée. |
DowngradeAsymmetricVisibilityRector::getRuleDefinition() | aucun. | Renvoie les métadonnées de règle Rector et des exemples. | RuleDefinition | aucun attendu. | Garde la documentation de la règle visible pour l’outillage Rector. |
DowngradeAsymmetricVisibilityRector::getNodeTypes() | aucun. | Sélectionne les types de nœud que la règle inspecte. | array<class-string<Node>> | aucun attendu. | La portée doit rester étroite pour des transformations déterministes. |
DowngradeAsymmetricVisibilityRector::refactor(Node $node) | Nœud AST. | Convertit la visibilité asymétrique là où elle est présente. | `Node | null` | Échec de règle Rector. |
DowngradeCloneWithRector | clone() avec surcharges de propriétés. | Clone accompagné d’assignations de propriétés explicites. | Utilise des variables temporaires générées. | Échec de règle Rector. | Doit s’exécuter après les rétrogradations des propriétés readonly. |
DowngradeCloneWithRector::getRuleDefinition() | aucun. | Renvoie les métadonnées de règle et des exemples. | RuleDefinition | aucun attendu. | Utilisé par le diagnostic Rector. |
DowngradeCloneWithRector::getNodeTypes() | aucun. | Sélectionne les nœuds de retour et d’expression. | array<class-string<Node>> | aucun attendu. | Garde la règle centrée sur la syntaxe clone-with. |
DowngradeCloneWithRector::refactor(Node $node) | Nœud AST. | Réécrit clone-with en clone plus assignations. | `array | null` | Échec de règle Rector. |
DowngradeTraitConstantsRector | Constantes de trait et références à celles-ci. | Propriétés statiques et références de propriétés. | Préserve la visibilité lorsque c’est possible. | Échec de règle Rector. | Supprime final parce que les propriétés des runtimes plus anciens ne peuvent pas être final. |
DowngradeTraitConstantsRector::getRuleDefinition() | aucun. | Renvoie les métadonnées de règle et des exemples. | RuleDefinition | aucun attendu. | Utilisé par le diagnostic Rector. |
DowngradeTraitConstantsRector::getNodeTypes() | aucun. | Sélectionne les nœuds de trait et de récupération de constante de classe. | array<class-string<Node>> | aucun attendu. | Limite la règle aux constantes de trait. |
DowngradeTraitConstantsRector::refactor(Node $node) | Nœud AST. | Réécrit les constantes de trait et leurs références en propriétés compatibles. | `Node | null` | Échec de règle Rector. |
Contrat de package généré
Section intitulée « Contrat de package généré »Utilise ce tableau pour voir ce que le builder émet : les noms de package qu’un projet en aval installe réellement, et quel package porte la distribution Pro.
| Package produit | Rôle d’exécution | Notes |
|---|---|---|
nextpdf/backport | Distribution d’exécution open-source générée. | Remplace les packages nextpdf/* sélectionnés pour la cible d’exécution. |
nextpdf/backport-pro | Distribution Pro propriétaire générée lorsque les sources Pro sont présentes. | Publiée séparément du package open-source. |
Notes de développement
Section intitulée « Notes de développement »- Le builder consomme des releases source et émet des artefacts générés. Ne corrige pas directement la sortie générée comme s’il s’agissait de la source de vérité.
- Chaque règle personnalisée doit disposer de tests sur fixtures avant d’entrer dans le pipeline de build.
- Les jobs de release doivent valider la sortie générée sur l’exécution cible, pas seulement sur l’hôte de build.