Installazione del Backport Builder di NextPDF

Strumenti di build — NON una dipendenza di runtime. Il builder va installato sulla workstation di un manutentore o su un runner CI. Un’applicazione a valle non installa mai il builder: installa il pacchetto prodotto dal builder.

In breve

Due destinatari distinti installano componenti diversi:

Un manutentore o operatore CI clona questo repository e ne installa le dipendenze di build. È l’unico contesto in cui nextpdf/backport-builder viene installato.
Un’applicazione a valle su un runtime PHP meno recente installa il pacchetto nextpdf/backport generato dal proprio canale di rilascio. L’applicazione non tocca mai questo repository.

Questa pagina copre entrambi gli scenari. Leggere la sezione corrispondente al proprio ruolo.

Installazione sull’host di build

Requisiti

Dipendenza	Vincolo	Fonte autorevole
PHP	`>=8.4 <9.0`	`composer.jsonrequire.php`
Composer	2.6+	Tabella degli ambienti in `CONTRIBUTING.md`
`rector/rector`	`^2.0`	`composer.jsonrequire-dev`
`phpstan/phpstan`	`^2.1`	`composer.jsonrequire-dev`
`phpunit/phpunit`	`^13.0`	`composer.jsonrequire-dev`

La pipeline di integrazione continua fornisce PHP 8.5 sia per il job di build sia per quello di dry-run. Un host di build con una qualsiasi versione di PHP compresa in >=8.4 <9.0 soddisfa il vincolo di Composer. Il parser deve accettare la sintassi più recente utilizzata dal codice sorgente. Verificato in base a .github/workflows/0-ci.yml.

Passaggi

Clonare il repository ed eseguire il checkout del ramo del target che si intende compilare. PHP74 è il ramo predefinito: produce la distribuzione PHP 7.4, solo core. PHP81 produce la distribuzione PHP 8.1 con tutti gli adapter.
Terminal window
```
git clone https://github.com/nextpdf-labs/backport.git
cd backport
git checkout PHP74
```
Installare le dipendenze di build. Non passare --no-dev: il motore Rector, PHPStan e PHPUnit si trovano in require-dev e la build non può essere eseguita senza di essi.
Terminal window
```
composer install --prefer-dist --no-progress
```
Verificare che la toolchain venga risolta correttamente. Lo script analyse esegue PHPStan al livello 10 su rector/rules e scripts. Un’esecuzione pulita dimostra che il codice di build stesso è solido prima di produrre qualsiasi output.
Terminal window
```
composer analyse
```
Eseguire i test delle fixture per le regole. Ogni regola Rector personalizzata dispone di una suite di fixture che verifica l’esatta trasformazione before/after.
Terminal window
```
composer test
```

Dopo il passaggio 4, l’host è pronto per la build. Proseguire con /integrations/backport/quickstart/ per le invocazioni di dry-run e di build completa.

Struttura attesa dell’albero dei sorgenti

La build unisce diversi repository sorgente in un unico albero. Lo script di merge si aspetta che siano directory di pari livello sotto un’unica radice dei sorgenti, richiamate per nome. Per il target PHP 8.1 legge nextpdf (core), nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter e nextpdf-Pro quando Pro è incluso. Per il target PHP 7.4 legge solo nextpdf. Verificato in base a scripts/merge-sources.php (MergeSources::__construct()). Specificare la radice dei sorgenti con --source-dir. Consultare /integrations/backport/configuration/ per il riferimento dei flag.

Utilizzo a valle del pacchetto prodotto

Un progetto eseguito su un runtime PHP meno recente installa la distribuzione prodotta, non questo builder.

Da PHP 8.1 a 8.3

composer require nextpdf/backport

Il pacchetto installato dichiara il vincolo >=8.1 <8.5 e sostituisce nextpdf/core, nextpdf/artisan, nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter e nextpdf/compat-legacy. Il codice dell’applicazione continua a importare il namespace NextPDF\ senza modifiche. Il pacchetto carica in autoload l’albero unito tramite l’unico prefisso PSR-4 NextPDF\ mappato su src/. Un autoloader PSR-4 aggiunge il nome relativo della classe a una directory di base registrata per il prefisso (PHP-FIG PSR-4). Verificato in base a scripts/adjust-composer.php (buildPublicAutoloadMap(), buildReplace()).

Da PHP 7.4 a 8.0

composer require nextpdf/backport

La distribuzione PHP 7.4 è solo core. Dichiara il vincolo >=7.4 <8.1 e sostituisce solo nextpdf/core. Gli adapter dei framework, il livello di compatibilità tcpdf e Pro non fanno parte della distribuzione PHP 7.4. Verificato in base a scripts/adjust-composer.php e scripts/build.php (il target PHP 7.4 forza la modalità solo core). Un progetto che necessita di un adapter per framework richiede PHP 8.1 o versione successiva.

Pro

composer require nextpdf/backport-pro

La distribuzione Pro è un pacchetto separato, nextpdf/backport-pro, con licenza proprietary. Richiede nextpdf/backport alla major.minor corrispondente e aggiunge phpseclib/phpseclib ^3.0. Viene prodotta solo per il target PHP 8.1. Verificato in base a scripts/adjust-composer.php (generateProComposer()).

La distribuzione PHP 7.4 e la distribuzione Pro si escludono a vicenda: non esiste alcuna build Pro per PHP 7.4, per come è costruito lo script di build.

Polyfill nel pacchetto prodotto

Il file composer.json generato richiede i pacchetti symfony/polyfill-* affinché le funzioni più recenti della libreria standard vengano risolte sul runtime di destinazione. Il target PHP 8.1 richiede i polyfill da PHP 8.2 a 8.5. Il target PHP 7.4 richiede inoltre i polyfill di PHP 8.0 e 8.1. Si tratta di dipendenze di runtime del pacchetto prodotto, non del builder. Verificato in base a scripts/adjust-composer.php (generatePublicComposer()).

Passi successivi

/integrations/backport/configuration/ — configurazioni di Rector, regole personalizzate e il riferimento dei flag di build.
/integrations/backport/quickstart/ — primo dry-run e build completa.