Configuration de NextPDF Backport Builder

Outillage de build — PAS une dépendance d’exécution. Tout ce qui figure sur cette page configure la manière dont le code source est transformé au moment du build. Rien de tout cela n’est livré à un runtime en aval.

En bref

La transformation est pilotée par trois fichiers de configuration Rector dans rector/config/ et par trois règles personnalisées dans rector/rules/. La configuration sélectionnée dépend de la cible. La cible PHP 8.1 utilise une seule passe Rector. La cible PHP 7.4 utilise un pipeline en deux passes avec une étape de correction intermédiaire. La seconde passe est nécessaire, car Rector ne peut pas résoudre les valeurs par défaut des cas d’énumération en une seule traversée.

Configurations Rector

Fichier	Rôle	Utilisé par
rector/config/rector-php81.php	Rétrogradation en une passe vers PHP 8.1	Cible PHP 8.1
rector/config/rector-php74-enums.php	Passe 1 — convertir les énumérations en classes à liste de constantes	Cible PHP 7.4
rector/config/rector-php74.php	Passe 2 — rétrogradation complète vers PHP 7.4	Cible PHP 7.4

Chaque configuration appelle la chaîne de jeux de rétrogradation de Rector (withDowngradeSets(php81: true) ou withDowngradeSets(php74: true)) pour les fonctionnalités que Rector gère nativement. Elle enregistre ensuite les règles personnalisées pour les fonctionnalités qu’il ne gère pas. Vérifié à partir des trois fichiers de rector/config/.

Règles d’exclusion

rector-php81.php et rector-php74.php excluent tous deux */tests/Benchmark/*. Les scripts de benchmark référencent des bibliothèques PDF externes que Rector ne peut pas résoudre, ce qui fait planter son résolveur de paramètres par défaut. rector-php74.php exclut aussi DowngradeHashAlgorithmXxHashRector. Cette règle intégrée plante sur les constantes MHASH_XXH* dépréciées dans les versions modernes de PHP, et le code source n’utilise pas xxHash. Vérifié à partir des appels withSkip() dans les deux fichiers.

Les trois règles personnalisées

Le dépôt fournit exactement trois règles Rector personnalisées. Toutes trois sont enregistrées dans rector-php81.php ; les règles de visibilité asymétrique, de clone-with et de constantes de trait sont également enregistrées dans rector-php74.php. C’est confirmé directement par tests/Rector/RectorRulesMetadataTest.php, qui instancie chaque règle et vérifie sa définition ainsi que ses types de nœuds.

DowngradeAsymmetricVisibilityRector

Supprime le modificateur de visibilité asymétrique en écriture. Une propriété ou un paramètre promu déclaré public private(set) devient un simple public. L’accès en lecture est préservé ; la restriction de mutateur au moment de la compilation est abandonnée. S’il ne reste aucune visibilité en lecture, la règle prend par défaut la valeur public. Transformation documentée par le code source, depuis tests/Rector/Fixtures/DowngradeAsymmetricVisibility/public_private_set.php.inc :

before

<?php

class Config {
    public private(set) float $x = 0.0;
    public private(set) string $name = '';
    public private(set) int $count = 0;
}

after

<?php

class Config {
    public float $x = 0.0;
    public string $name = '';
    public int $count = 0;
}

DowngradeCloneWithRector

Réécrit la forme fonctionnelle clone() dotée d’un tableau de remplacements en un clone suivi d’affectations explicites de propriétés, puis du retour d’une variable temporaire. Le compteur de variables temporaires est réinitialisé pour chaque fichier. Cette règle doit s’exécuter après la règle de suppression des propriétés en lecture seule, car l’affectation développée échouerait sinon sur une propriété en lecture seule. Transformation documentée par le code source, depuis tests/Rector/Fixtures/DowngradeCloneWith/return_clone_with.php.inc :

before

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self {
        return clone($this, ['width' => $width, 'height' => $height]);
    }
}

after

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self
    {
        $__cloneResult1 = clone $this;
        $__cloneResult1->width = $width;
        $__cloneResult1->height = $height;
        return $__cloneResult1;
    }
}

La règle a des limitations documentées. La correspondance des arguments utilise un motif non récursif ; les valeurs de remplacement contenant des parenthèses imbriquées ne sont donc pas prises en charge. Seules les clés de tableau de type chaîne sont résolues en noms de propriétés. Vérifié à partir de rector/rules/DowngradeCloneWithRector.php et de sa suite de fixtures.

DowngradeTraitConstantsRector

Convertit les constantes de trait en propriétés statiques. Une constante de trait est une fonctionnalité que les runtimes plus anciens rejettent avec « Traits cannot have constants ». La règle réécrit également les références self::CONST et static::CONST vers la forme à propriété statique. La visibilité est préservée ; le modificateur final est retiré, car les propriétés ne peuvent pas être final sur la cible plus ancienne. Une constante de classe typée devient une propriété typée. Transformation documentée par le code source, depuis tests/Rector/Fixtures/DowngradeTraitConstants/private_constant.php.inc :

before

<?php

trait HasLimit
{
    private const MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::MAX_SIZE;
    }
}

after

<?php

trait HasLimit
{
    private static $MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::$MAX_SIZE;
    }
}

Le pipeline PHP 7.4 en deux passes

La cible PHP 7.4 ne peut pas s’exécuter en une seule passe. Le résolveur de valeurs de paramètres par défaut de Rector plante sur les valeurs par défaut de cas d’énumération dans la promotion de constructeur. Le script de build exécute donc :

1. Passe 1 — pré-traitement des énumérations. rector-php74-enums.php exécute uniquement la règle intégrée qui convertit une énumération en classe à liste de constantes. Après cette passe, les cas d’énumération sont de simples constantes de classe.
2. Vidage du cache. Le cache de Rector est vidé afin que la seconde passe ne voie pas d’arbre obsolète.
3. Corrections de post-traitement. scripts/build.php réécrit les motifs que la règle énumération vers classe ne couvre pas. Les anciennes méthodes d’instance des énumérations deviennent statiques. Les accès EnumClass::Case->value et ->name sont résolus. Les arguments nommés que Rector n’a pas pu lier sont aplatis en arguments positionnels. Sans ces corrections, ces motifs syntaxiques provoqueraient une erreur d’analyse sur PHP 7.4.
4. Passe 2 — rétrogradation complète. rector-php74.php exécute la chaîne complète de rétrogradation PHP 7.4 ainsi que les règles personnalisées.

Vérifié à partir de scripts/build.php (runRector(), postProcessFixups()).

Référence des options de build

scripts/build.php est l’orchestrateur. Ses options, vérifiées à partir de l’appel getopt() et du constructeur Build :

Indicateur	Valeur par défaut	Effet
--version=<x.y.z>	2.0.0	Version écrite dans les composer.json et CHANGELOG.md générés
--source-dir=<path>	c:/Users/admin/Documents	Racine contenant les dépôts source frères
--output-dir=<path>	<repo>/output	Emplacement où la distribution générée est écrite
--target=php74 | --target=php81	php81	Cible de rétrogradation. php74 force le mode core uniquement et désactive Pro
--dry-run	désactivé	Exécuter chaque étape en mode rapport uniquement ; les copies et Rector sont ignorés
--no-pro	désactivé	Exclure le paquet Pro (cible PHP 8.1 uniquement ; PHP 7.4 l’exclut déjà)

Toute valeur invalide pour --target lève InvalidArgumentException avant le début du moindre traitement. Vérifié à partir de Build::__construct() (garde VALID_TARGETS).

Scripts Composer

Script	Commande	Rôle
composer test	phpunit	Exécuter les suites de fixtures des règles
composer analyse	phpstan analyse rector/rules scripts --level=10	Analyser statiquement le code de build
composer build	php scripts/build.php	Build complet
composer build:dry	php scripts/build.php --dry-run	Build en simulation

Vérifié à partir de composer.jsonscripts.

Et ensuite

• /integrations/backport/quickstart/ — exécuter la simulation et le build complet.
• /integrations/backport/troubleshooting/ — comprendre la signification de chaque étape d’échec.