Integrazione del backport di NextPDF

Strumenti di build — NON una dipendenza di runtime. I manutentori usano questo pacchetto per produrre le distribuzioni backport di NextPDF per PHP 7.4 e PHP 8.1. Le applicazioni non devono mai aggiungerlo come dipendenza di runtime.

In sintesi

I punti di integrazione sono due e distinti. L’host di build integra il repository del builder in un flusso di rilascio. L’applicazione a valle integra il pacchetto prodotto, nextpdf/backport, nel proprio albero delle dipendenze. Il builder non entra mai nell’albero delle dipendenze di un’applicazione.

Installazione (solo host di build)

Il builder dichiara "type": "project" in composer.json: è quindi un repository di progetto, non una libreria. Integrarlo tramite clone e installazione dev, non con un composer require:

git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
composer install --prefer-dist --no-progress

Effettuare il checkout del branch corrispondente al target da produrre. Usare PHP74 (il valore predefinito) per la distribuzione PHP 7.4 con solo il core. Usare PHP81 per la distribuzione PHP 8.1 con tutti gli adattatori. Non passare --no-dev. La build richiede il motore Rector, PHPStan e PHPUnit, che sono dipendenze dev. Verificato rispetto a composer.json (type, require-dev) e al modello a doppio branch in /integrations/backport/overview/.

Boot e rilevamento automatico

Non è previsto alcun rilevamento automatico del framework. In fase di build, scripts/build.php carica Rector e le tre regole personalizzate per l’albero della sintassi astratta tramite require_once espliciti e l’autoloading PSR-4 di Composer. La sequenza di boot completa e il rilevamento dei moduli sorgente sono documentati in /integrations/backport/boot-and-discovery/.

Binding del container

Non applicabile. Il builder è uno strumento CLI e non dispone di un container per l’iniezione delle dipendenze. Verificato rispetto alla struttura del repository e a composer.jsonautoload.

Configurazione di pubblicazione

La «configurazione di pubblicazione» non è un file: è l’insieme dei flag di build e delle definizioni fisse dei pacchetti in scripts/adjust-composer.php:

• Mappa dei target. --target=php81 produce nextpdf/backport (vincolo >=8.1 <8.5, sostituisce core, adattatori e compat-legacy) e, quando incluso, nextpdf/backport-pro. --target=php74 produce nextpdf/backport (vincolo >=7.4 <8.1, sostituisce solo nextpdf/core) e non produce Pro.
• Esclusione. --no-pro esclude il pacchetto Pro sul target PHP 8.1. Il target PHP 7.4, per costruzione, esclude Pro e tutti gli adattatori.
• Versione. La build registra --version (o il tag di rilascio con la v iniziale rimossa) nel composer.json generato e in CHANGELOG.md.

Verificato rispetto a scripts/build.php e scripts/adjust-composer.php (generatePublicComposer(), generateProComposer(), buildReplace()). Il riferimento completo dei flag si trova in /integrations/backport/configuration/.

Integrazione nel flusso di rilascio

Il builder si integra in un flusso di rilascio tramite i workflow di GitHub Actions in .github/workflows/. 0-ci.yml impone un gate a ogni modifica su uno dei due branch permanenti con PHPStan, i test delle regole e un dry-run. build.yml produce e rilascia la distribuzione in occasione di un evento repository-dispatch source-release oppure tramite un dispatch manuale. Il modello operativo completo — trigger, lane, matrice di validazione e rilascio condiviso — è documentato in /integrations/backport/production-usage/.

Smoke test di consumo dell’output

La pipeline di rilascio è lo smoke test di integrazione. Dopo la build, il workflow porta il runner sul PHP target ed esegue php -l sull’intero sorgente emesso. Quindi installa e mette alla prova il pacchetto prodotto sull’intera matrice di validazione (PHP 8.1–8.4 per la lane PHP 8.1, PHP 7.4 e 8.0 per la lane PHP 7.4). Una distribuzione che un runtime target rifiuterebbe non arriva a un rilascio. Verificato rispetto a .github/workflows/build.yml (i job di controllo della sintassi e validate-*). È possibile eseguire localmente lo smoke test dell’output prodotto nello stesso modo, con il comando Docker stampato dallo stage di validazione — vedere /integrations/backport/quickstart/.

Punti di ingresso pubblici

La superficie pubblica del builder è l’orchestratore CLI e i suoi alias di script Composer, non un eseguibile bin/.

Punto di ingresso	Si risolve in	Scopo
composer build	php scripts/build.php	Build completa
composer build:dry	php scripts/build.php --dry-run	Build dry-run
composer test	phpunit	Suite di fixture per le regole
composer analyse	phpstan analyse rector/rules scripts --level=10	Analizzare staticamente il codice di build

Verificato rispetto a composer.jsonscripts. I punti di ingresso del pacchetto a valle sono i simboli API originali NextPDF\, che il backport lascia invariati. Il pacchetto sostituisce i pacchetti sorgente ed effettua l’autoload dell’albero unificato tramite l’unico prefisso PSR-4.

Vedere anche

• /integrations/backport/overview/ — che cos’è il builder e che cosa produce.
• /integrations/backport/boot-and-discovery/ — sequenza di boot e rilevamento dei sorgenti.
• /integrations/backport/install/ — installazione sull’host di build e a valle.
• /integrations/backport/production-usage/ — la pipeline di rilascio.