Installer le générateur de backport de NextPDF

Outillage de build — pas une dépendance d’exécution. Le générateur s’installe sur le poste de travail d’un mainteneur ou sur un exécuteur CI. Une application en aval n’installe jamais le générateur ; elle installe le paquet produit par celui-ci.

En bref

Deux publics distincts installent deux éléments différents :

Un mainteneur ou opérateur CI clone ce dépôt et installe ses dépendances de build. C’est le seul contexte dans lequel nextpdf/backport-builder est installé.
Une application en aval exécutée dans un environnement d’exécution PHP plus ancien installe le paquet nextpdf/backport généré depuis son canal de publication. L’application ne touche jamais à ce dépôt.

Cette page couvre les deux cas. Lis la section qui correspond à ton rôle.

Installation sur l’hôte de build

Prérequis

Dépendance	Contrainte	Source de référence
PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
Composer	2.6+	`CONTRIBUTING.md` tableau d’environnement
`rector/rector`	`^2.0`	`composer.jsonrequire-dev`
`phpstan/phpstan`	`^2.1`	`composer.jsonrequire-dev`
`phpunit/phpunit`	`^13.0`	`composer.jsonrequire-dev`

Le workflow d’intégration continue provisionne PHP 8.5 à la fois pour le job de build et pour le job de simulation (dry-run). Un hôte de build exécuté avec n’importe quelle version de PHP comprise dans >=8.4 <9.0 satisfait la contrainte Composer. L’analyseur doit accepter la syntaxe la plus récente utilisée par les sources. Vérifié par rapport à .github/workflows/0-ci.yml.

Étapes

Clone le dépôt et bascule sur la branche correspondant à la cible que tu comptes générer. PHP74 est la branche par défaut ; elle produit la distribution PHP 7.4, cœur uniquement. PHP81 produit la distribution PHP 8.1 avec tous les adaptateurs.
Fenêtre de terminal
```
git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
```
Installe les dépendances de build. Ne passe pas --no-dev : le moteur Rector, PHPStan et PHPUnit résident dans require-dev, et le build ne peut pas s’exécuter sans eux.
Fenêtre de terminal
```
composer install --prefer-dist --no-progress
```
Vérifie que la chaîne d’outils se résout correctement. Le script analyse exécute PHPStan au niveau 10 sur rector/rules et scripts. Une exécution sans erreur prouve que le code de build lui-même est sain avant de produire la moindre sortie.
Fenêtre de terminal
```
composer analyse
```
Exécute les tests de fixtures des règles. Chaque règle Rector personnalisée dispose d’une suite de fixtures qui vérifie la transformation before/after exacte.
Fenêtre de terminal
```
composer test
```

Après l’étape 4, l’hôte est prêt pour la génération. Passe à /integrations/backport/quickstart/ pour les invocations de simulation (dry-run) et de build complet.

Arborescence source attendue

Le build fusionne plusieurs dépôts source en une seule arborescence. Le script de fusion s’attend à les trouver sous forme de répertoires frères, sous une même racine source, identifiés par leur nom. Pour la cible PHP 8.1, il lit nextpdf (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, il lit uniquement nextpdf. Vérifié par rapport à scripts/merge-sources.php (MergeSources::__construct()). Fournis la racine source avec --source-dir. Consulte /integrations/backport/configuration/ pour la référence des options.

Consommation en aval du paquet produit

Un projet exécuté dans un environnement d’exécution PHP plus ancien installe la distribution produite, pas ce générateur.

PHP 8.1 à 8.3

composer require nextpdf/backport

Le paquet installé porte la contrainte >=8.1 <8.5 et remplace nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter et nextpdf/compat-legacy. Le code applicatif continue d’importer l’espace de noms NextPDF\ sans changement. Le paquet charge automatiquement l’arborescence fusionnée via l’unique préfixe PSR-4 NextPDF\ mappé sur src/. Un autoloader PSR-4 ajoute le nom de classe relatif à un répertoire de base enregistré pour le préfixe (PHP-FIG PSR-4). Vérifié par rapport à scripts/adjust-composer.php (buildPublicAutoloadMap(), buildReplace()).

PHP 7.4 à 8.0

composer require nextpdf/backport

La distribution PHP 7.4 est cœur uniquement. Elle porte la contrainte >=7.4 <8.1 et ne remplace que nextpdf/core. Les adaptateurs de framework, la couche de compatibilité tcpdf et Pro ne font pas partie de la distribution PHP 7.4. Vérifié par rapport à scripts/adjust-composer.php et scripts/build.php (la cible PHP 7.4 force le cœur uniquement). Un projet qui nécessite un adaptateur de framework doit utiliser PHP 8.1 ou plus récent.

Pro

composer require nextpdf/backport-pro

La distribution Pro est un paquet distinct, nextpdf/backport-pro, sous licence proprietary. Elle requiert nextpdf/backport au major.minor correspondant et ajoute phpseclib/phpseclib ^3.0. Elle n’est produite que pour la cible PHP 8.1. Vérifié par rapport à scripts/adjust-composer.php (generateProComposer()).

La distribution PHP 7.4 et la distribution Pro sont mutuellement exclusives : il n’existe aucun build Pro pour PHP 7.4, par construction du script de build.

Polyfills dans le paquet produit

Le composer.json généré requiert des paquets symfony/polyfill-* afin que les fonctions plus récentes de la bibliothèque standard se résolvent dans l’environnement d’exécution cible. La cible PHP 8.1 requiert des polyfills pour PHP 8.2 à 8.5. La cible PHP 7.4 requiert en outre les polyfills PHP 8.0 et 8.1. Ce sont des dépendances d’exécution du paquet produit, pas du générateur. Vérifié par rapport à scripts/adjust-composer.php (generatePublicComposer()).

Étapes suivantes

/integrations/backport/configuration/ — configurations Rector, règles personnalisées et référence des options de build.
/integrations/backport/quickstart/ — première simulation (dry-run) et build complet.