Guida rapida di NextPDF Backport Builder

Strumento di build — NON una dipendenza di runtime. Questa procedura va eseguita su un host del maintainer o di integrazione continua (CI). L’archivio prodotto è quello utilizzato da un progetto a valle. I passaggi qui descritti non vengono mai eseguiti su un server applicativo.

In sintesi

La procedura prevede tre operazioni. Per prima cosa, eseguire la simulazione (dry-run), che dimostra che il flusso è collegato correttamente senza toccare alcun file. Poi eseguire una build completa per PHP 8.1. Infine eseguire una build completa per PHP 7.4. Ogni passaggio richiede un solo comando ed è supportato da uno script Composer o da un’invocazione documentata di scripts/build.php.

Prerequisiti

• Un host di build con PHP >=8.4 <9.0, con le dipendenze di build installate (composer install, senza --no-dev). Vedere /integrations/backport/install/.
• I repository dei sorgenti estratti come directory affiancate sotto un’unica radice dei sorgenti. La build per PHP 8.1 legge nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter e nextpdf-Pro (per Pro). La build per PHP 7.4 legge solo nextpdf. Verificato in base a scripts/merge-sources.php.

Passaggio 1 — simulazione (dry-run)

La simulazione (dry-run) esegue ogni fase in modalità solo report. L’unione elenca ciò che copierebbe. Rector viene annunciato ma non eseguito. Le fasi di generazione del file Composer, copia degli asset e convalida indicano l’operazione che eseguirebbero. Non viene scritto nulla. Eseguire prima questa simulazione per confermare che la disposizione dei sorgenti e i flag siano corretti, poiché è la verifica più rapida.

composer build:dry

composer build:dry equivale a php scripts/build.php --dry-run. Verificato in base a composer.jsonscripts e scripts/build.php (il ramo dryRun in ciascuna fase). Con i flag predefiniti, il target è php81 e la radice dei sorgenti coincide con quella predefinita dello script. È possibile sovrascrivere l’uno o l’altro, come mostrato nel passaggio 2.

Se la simulazione (dry-run) segnala un repository dei sorgenti mancante, fallisce immediatamente indicandone il nome. Correggere la disposizione dei sorgenti prima di proseguire — vedere /integrations/backport/troubleshooting/.

Passaggio 2 — build completa per PHP 8.1

La build per PHP 8.1 esegue più passaggi in sequenza. Unisce il core, gli adattatori dei framework e il livello di compatibilità tcpdf. Esegue la configurazione Rector a passaggio singolo. Genera il nextpdf/backportcomposer.json. Copia la licenza, scrive un CHANGELOG.md e conta i file PHP prodotti.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output

Verificato in base al punto di ingresso CLI di scripts/build.php. Le cinque fasi vengono eseguite nell’ordine seguente: unione dei sorgenti, esecuzione del downgrade Rector, generazione di composer.json, copia degli asset statici, convalida dell’output. Ogni fase stampa un segno di spunta in caso di successo. La prima fase che fallisce interrompe la build e stampa l’errore corrispondente. Per escludere Pro, aggiungere --no-pro.

In caso di successo, l’orchestratore stampa il tempo trascorso e il percorso di output. Quando Pro è incluso, stampa anche il percorso di output di Pro. La directory di output contiene quindi src/, tests/, un composer.json generato che dichiara la mappa replace e i requisiti dei polyfill, oltre a LICENSE e CHANGELOG.md.

Passaggio 3 — build completa per PHP 7.4

La build per PHP 7.4 riguarda solo il core ed esegue il flusso a due passaggi. Le fasi sono la pre-elaborazione degli enum, una pulizia della cache, le correzioni post-Rector e infine il downgrade completo.

php scripts/build.php \
  --version=2.0.0 \
  --source-dir=/path/to/sources \
  --output-dir=./output-php74 \
  --target=php74

Verificato in base a scripts/build.php. Qui, --target=php74 forza la modalità solo-core e disabilita Pro; runRector() seleziona il percorso a due passaggi. Il composer.json generato usa il vincolo >=7.4 <8.1, sostituisce solo nextpdf/core e aggiunge i polyfill per PHP 8.0 e 8.1 oltre ai polyfill per 8.2–8.5.

Passaggio 4 — leggere l’output

La fase di convalida conta i file PHP in output/src e fallisce se il conteggio è zero. Non esegue un controllo di sintassi locale, perché l’interprete locale è la versione moderna di PHP dell’host di build, non il target. Stampa il comando Docker per la convalida rispetto al runtime di destinazione effettivo. Verificato in base a scripts/build.php (validateOutput()).

Per una convalida completa, eseguire il controllo di sintassi con il PHP di destinazione. Il flusso di rilascio fa esattamente questo. Esegue il controllo di sintassi dell’output su PHP 8.1 (o PHP 7.4), quindi installa l’output e lo collauda sull’intera matrice di supporto. Vedere /integrations/backport/production-usage/.

Cosa è stato compilato

Artefatto	Compilato da	Vincolo	Sostituisce
nextpdf/backport (PHP 8.1)	Passaggio 2	>=8.1 <8.5	core + artisan + laravel + symfony + codeigniter + compat-legacy
nextpdf/backport-pro (PHP 8.1)	Passaggio 2, quando Pro è incluso	>=8.1 <8.5	nextpdf/pro
nextpdf/backport (PHP 7.4)	Passaggio 3	>=7.4 <8.1	nextpdf/core

Verificato in base a scripts/adjust-composer.php.

Passi successivi

• /integrations/backport/production-usage/ — collegare questa procedura al flusso di rilascio basato su eventi.
• /integrations/backport/configuration/ — il riferimento per le regole e i flag alla base di questi comandi.
• /integrations/backport/troubleshooting/ — ogni errore di fase e il relativo significato.