Installation de Backport

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

1. 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.

   git clone https://github.com/nextpdf-labs/backport.git
   cd backport
   git checkout PHP74

2. 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.

   composer install --prefer-dist --no-progress

3. 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.

   composer analyse

4. 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.

   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.

Cycle de vie du support

La cible PHP 7.4 (cœur uniquement) est prise en charge jusqu’au 2027-12-31, puis abandonnée. Prévois un passage à PHP 8.1 ou plus récent avant cette date. Le plancher PHP 8.1 n’est pas figé : il suit la fin de vie de sécurité (security end-of-life) du PHP amont, si bien que la plus basse cible 8.x prise en charge avance à mesure que les versions de PHP atteignent leur fin de vie de sécurité.

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.