NextPDF : vue d’ensemble du Backport Builder
Outil de build, pas une dépendance d’exécution. Les mainteneurs de NextPDF utilisent ce paquet pour produire des distributions de NextPDF compatibles avec PHP 8.1+ et PHP 7.4+. Les applications ne doivent jamais l’ajouter comme dépendance d’exécution.
Le NextPDF Backport Builder est l’infrastructure de build qui produit une distribution rétroportée de l’écosystème NextPDF pour les runtimes PHP antérieurs à la base de développement. NextPDF lui-même cible une version récente de PHP et emploie une syntaxe que les interpréteurs plus anciens rejettent. Le builder fait passer le code source par Rector, un moteur de transformation d’arbre syntaxique abstrait, puis émet des paquets dont la syntaxe est acceptée par un runtime PHP 8.1 ou PHP 7.4.
Le nom du paquet Composer est nextpdf/backport-builder. Il déclare "type": "project" et n’entraîne aucune dépendance d’exécution envers NextPDF. Ses seuls prérequis sont le moteur de build (rector/rector), l’analyse statique (phpstan/phpstan), le lanceur de tests (phpunit/phpunit) et un ensemble de paquets symfony/polyfill-* utilisés dans la sortie générée. Ce point est vérifié dans composer.json à la racine du dépôt.
Ce que ce paquet n’est pas
Section intitulée « Ce que ce paquet n’est pas »Ce dépôt ne contient pas le moteur NextPDF. Il contient les règles et les scripts qui transforment le moteur en version rétroportée. Trois séparations en découlent :
- Tu n’installes pas ceci pour produire des PDF. L’artefact que tu installes est
nextpdf/backport, produit par ce builder. Le builder reste sur l’hôte du mainteneur ou de la CI. - Tu ne développes pas dans le code généré. La distribution générée est un artefact produit par la machine, en lecture seule. Adresse les rapports de bogues et les demandes de fonctionnalités aux dépôts source
nextpdf/*d’origine. - La sortie est livrée sous forme de tags de version, et non de branches de ce dépôt. Le pipeline de release tague l’arbre généré et joint des archives à une release GitHub.
Ce qu’il produit
Section intitulée « Ce qu’il produit »Le builder émet des paquets Composer dont les noms et les licences sont fixés par scripts/adjust-composer.php :
| Paquet produit | Licence | Portée | Construit quand |
|---|---|---|---|
nextpdf/backport | Apache-2.0 | Le cœur, ainsi que les adaptateurs de framework et la couche de compatibilité tcpdf pour la cible PHP 8.1 | Toujours |
nextpdf/backport-pro | proprietary | Le module Pro, émis comme paquet distinct | Cible PHP 8.1, lorsque la source Pro est présente et que Pro n’est pas exclu |
Le paquet nextpdf/backport déclare des entrées Composer replace afin qu’une fois installé, il satisfasse les contraintes des paquets d’origine. Pour la cible PHP 8.1, les paquets remplacés sont nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter et nextpdf/compat-legacy. Pour la cible PHP 7.4, seul nextpdf/core est remplacé, car le build PHP 7.4 ne contient que le cœur. Ce point est vérifié dans scripts/adjust-composer.php (buildReplace()).
L’autoloader d’un consommateur résout l’arbre fusionné via un unique préfixe PSR-4, NextPDF\, associé à src/. PSR-4 associe un préfixe de namespace à un répertoire de base et résout chaque nom de classe pleinement qualifié vers un fichier situé sous ce répertoire — voir PHP-FIG PSR-4. Le paquet Pro associe NextPDF\Pro\ à son propre src/.
Matrice PHP prise en charge
Section intitulée « Matrice PHP prise en charge »La matrice ci-dessous indique uniquement ce que les configurations Rector et les scripts de build imposent. L’hôte de build exécute toujours une version récente de PHP. La sortie cible une version plus ancienne.
| Aspect | Valeur | Preuve |
|---|---|---|
| PHP de l’hôte de build | >=8.4 <9.0 | composer.jsonrequire.php |
| PHP de build/test en CI | 8.5 | .github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5') |
| Contrainte de sortie de la cible PHP 8.1 | >=8.1 <8.5 | scripts/adjust-composer.php (generatePublicComposer()) |
| Contrainte de sortie de la cible PHP 7.4 | >=7.4 <8.1 | scripts/adjust-composer.php (generatePublicComposer()) |
| Portée de la cible PHP 8.1 | Cœur + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, distinct) | scripts/merge-sources.php, scripts/adjust-composer.php |
| Portée de la cible PHP 7.4 | Cœur uniquement | scripts/build.php (--target=php74 force le cœur uniquement, Pro désactivé) |
Le build PHP 8.1 est validé sur PHP 8.1, 8.2, 8.3 et 8.4. Le build PHP 7.4 est validé sur PHP 7.4 et 8.0. Ce point est vérifié dans les matrices de jobs validate-php81 et validate-php74 de .github/workflows/build.yml. Ce sont les runtimes exercés par le pipeline. Il s’agit d’un ensemble de validation observé, et non d’une revendication de conformité.
Le modèle à deux branches
Section intitulée « Le modèle à deux branches »Ce dépôt n’a pas de branche main. PHP74 est la branche par défaut, et PHP81 est l’autre branche permanente. La branche sur laquelle tu te trouves détermine deux choses : la cible par défaut du build local et l’ensemble de sources qui est fusionné. Un changement qui affecte les deux cibles est appliqué à chaque branche via sa propre pull request. Le workflow d’intégration continue s’exécute à la fois sur PHP74 et PHP81. Ce point est vérifié avec git branch -a et .github/workflows/0-ci.yml (branches: [PHP74, PHP81]).
Comment se déroule une release
Section intitulée « Comment se déroule une release »Le chemin de release est piloté par les événements. Lorsque l’organisation source NextPDF publie un tag de release, un événement repository-dispatch de type source-release déclenche le workflow de build. Le workflow extrait chaque dépôt source au tag correspondant, exécute le pipeline, vérifie la syntaxe de la sortie sur le runtime cible, la valide sur l’ensemble de la matrice de prise en charge et joint les archives à une release GitHub. Le tag de version suit le Semantic Versioning : un numéro de version est MAJOR.MINOR.PATCH sur une API publique déclarée (Semantic Versioning 2.0.0 §2). Ce point est vérifié dans .github/workflows/build.yml.
Où aller ensuite
Section intitulée « Où aller ensuite »- /integrations/backport/install/ — comment obtenir le builder sur un hôte de build et comment un consommateur installe le paquet produit.
- /integrations/backport/configuration/ — les configurations Rector, les règles personnalisées et les options de build.
- /integrations/backport/quickstart/ — une invocation exécutable en simulation (dry-run) et en build complet, étayée par les sources.
- /integrations/backport/production-usage/ — l’intégration du builder dans un workflow de release.
- /integrations/backport/troubleshooting/ — les modes de défaillance dont le pipeline se prémunit et comment les interpréter.
- /integrations/backport/security-and-operations/ — la posture de chaîne d’approvisionnement, la limite de confiance et les garanties opérationnelles.
- /integrations/backport/boot-and-discovery/ — comment le builder découvre les modules source et démarre.
- /integrations/backport/integration/ — le contrat d’intégration de l’hôte de build.