Panoramica di NextPDF Backport Builder
Strumenti di build — NON una dipendenza di runtime. I manutentori di NextPDF usano questo pacchetto per produrre distribuzioni di NextPDF compatibili con PHP 8.1+ e PHP 7.4+. Le applicazioni non devono mai aggiungere questo pacchetto come dipendenza di runtime.
In sintesi
Sezione intitolata “In sintesi”NextPDF Backport Builder è l’infrastruttura di build che produce una distribuzione retrocompatibile dell’ecosistema NextPDF per runtime PHP precedenti rispetto alla baseline di sviluppo. NextPDF è scritto per una versione moderna di PHP e usa una sintassi che gli interpreti più datati rifiutano. Il builder elabora il codice sorgente tramite Rector, un motore di trasformazione dell’albero sintattico astratto, e genera pacchetti con una sintassi accettata da un runtime PHP 8.1 o PHP 7.4.
Il nome del pacchetto Composer è nextpdf/backport-builder. Dichiara "type": "project" e non introduce alcuna dipendenza di runtime di NextPDF. I suoi unici requisiti sono il motore di build (rector/rector), l’analisi statica (phpstan/phpstan), il test runner (phpunit/phpunit) e un insieme di pacchetti symfony/polyfill-* usati nell’output generato. Questo è verificato rispetto a composer.json nella radice del repository.
Che cosa NON è questo pacchetto
Sezione intitolata “Che cosa NON è questo pacchetto”Questo repository non contiene il motore di NextPDF. Contiene le regole e gli script che trasformano il motore in una forma retrocompatibile. Da qui derivano tre distinzioni:
- Non si installa questo pacchetto per generare PDF. L’artefatto da installare è
nextpdf/backport, prodotto da questo builder. Il builder resta sull’host del manutentore o della CI. - Non si sviluppa sul codice generato. La distribuzione generata è un artefatto in sola lettura prodotto da una macchina. Inviare segnalazioni di bug e richieste di funzionalità ai repository sorgente originali
nextpdf/*. - L’output viene distribuito come tag di versione, non come branch di questo repository. La pipeline di rilascio applica un tag all’albero generato e allega gli archivi a una release GitHub.
Che cosa produce
Sezione intitolata “Che cosa produce”Il builder genera pacchetti Composer i cui nomi e licenze sono definiti da scripts/adjust-composer.php:
| Pacchetto prodotto | Licenza | Ambito | Generato quando |
|---|---|---|---|
nextpdf/backport | Apache-2.0 | Core, più gli adapter di framework e il livello di compatibilità tcpdf per il target PHP 8.1 | Sempre |
nextpdf/backport-pro | proprietary | Il modulo Pro, generato come pacchetto separato | Target PHP 8.1, quando il sorgente Pro è presente e Pro non è escluso |
Il pacchetto nextpdf/backport dichiara voci Composer replace in modo che, una volta installato, soddisfi i vincoli dei pacchetti originali. Per il target PHP 8.1 i pacchetti sostituiti sono nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter e nextpdf/compat-legacy. Per il target PHP 7.4 viene sostituito solo nextpdf/core, perché la build PHP 7.4 è solo core. Questo è verificato rispetto a scripts/adjust-composer.php (buildReplace()).
L’autoloader di un consumer risolve l’albero unito tramite un singolo prefisso PSR-4, NextPDF\ mappato su src/. PSR-4 mappa un prefisso di namespace su una directory di base e risolve ogni nome di classe completo in un file al suo interno — vedere PHP-FIG PSR-4. Il pacchetto Pro mappa NextPDF\Pro\ sul proprio src/.
Matrice PHP supportata
Sezione intitolata “Matrice PHP supportata”La matrice seguente indica solo ciò che impongono le configurazioni di Rector e gli script di build. L’host di build esegue sempre una versione moderna di PHP. L’output punta a una versione più datata.
| Aspetto | Valore | Evidenza |
|---|---|---|
| PHP dell’host di build | >=8.4 <9.0 | composer.jsonrequire.php |
| PHP di build/test CI | 8.5 | .github/workflows/0-ci.yml, build.yml (shivammathur/setup-phpphp-version: '8.5') |
| Vincolo di output del target PHP 8.1 | >=8.1 <8.5 | scripts/adjust-composer.php (generatePublicComposer()) |
| Vincolo di output del target PHP 7.4 | >=7.4 <8.1 | scripts/adjust-composer.php (generatePublicComposer()) |
| Ambito del target PHP 8.1 | Core + Artisan + Laravel + Symfony + CodeIgniter + compat-legacy (+ Pro, separato) | scripts/merge-sources.php, scripts/adjust-composer.php |
| Ambito del target PHP 7.4 | Solo core | scripts/build.php (--target=php74 forces core-only, Pro disabled) |
La build PHP 8.1 è validata su PHP 8.1, 8.2, 8.3 e 8.4. La build PHP 7.4 è validata su PHP 7.4 e 8.0. Questo è verificato rispetto alle matrici dei job validate-php81 e validate-php74 in .github/workflows/build.yml. Questi sono i runtime su cui la pipeline esegue i controlli. Sono un insieme di validazione osservato, non un’affermazione di conformità.
Il modello a doppio branch
Sezione intitolata “Il modello a doppio branch”Questo repository non ha un branch main. PHP74 è il branch predefinito e PHP81 è il secondo branch permanente. Il branch su cui ci si trova determina due aspetti: il target predefinito della build locale e l’insieme di sorgenti che viene unito. Una modifica che interessa entrambi i target viene applicata a ciascun branch tramite la propria pull request. Il workflow di integrazione continua viene eseguito sia su PHP74 sia su PHP81. Questo è verificato rispetto a git branch -a e .github/workflows/0-ci.yml (branches: [PHP74, PHP81]).
Come avviene una release
Sezione intitolata “Come avviene una release”Il percorso di rilascio è guidato dagli eventi. Quando l’organizzazione sorgente di NextPDF pubblica un tag di release, un evento di repository-dispatch di tipo source-release attiva il workflow di build. Il workflow effettua il checkout di ogni repository sorgente al tag corrispondente, esegue la pipeline, verifica la sintassi dell’output sul runtime di destinazione, lo valida sull’intera matrice di supporto e allega gli archivi a una release GitHub. Il tag di versione segue il Semantic Versioning — un numero di versione ha la forma MAJOR.MINOR.PATCH per un’API pubblica dichiarata (Semantic Versioning 2.0.0 §2). Questo è verificato rispetto a .github/workflows/build.yml.
Dove andare dopo
Sezione intitolata “Dove andare dopo”- /integrations/backport/install/ — come ottenere il builder su un host di build e come installare il pacchetto prodotto lato consumer.
- /integrations/backport/configuration/ — le configurazioni di Rector, le regole personalizzate e i flag di build.
- /integrations/backport/quickstart/ — un dry run eseguibile e un’invocazione di build completa, basata sul codice sorgente.
- /integrations/backport/production-usage/ — l’integrazione del builder in un workflow di rilascio.
- /integrations/backport/troubleshooting/ — le modalità di errore da cui la pipeline si protegge e come interpretarle.
- /integrations/backport/security-and-operations/ — la postura della supply chain, il confine di fiducia e le garanzie operative.
- /integrations/backport/boot-and-discovery/ — come il builder individua i moduli sorgente e si avvia.
- /integrations/backport/integration/ — il contratto di integrazione dell’host di build.