Riferimento API per Backport Builder

In breve

Backport Builder è uno strumento di build, non una libreria di runtime. La sua interfaccia pubblica comprende il set di comandi di build (scripts/build.php e i relativi wrapper composer build*), le quattro classi a livello di script che li implementano (Build, MergeSources, AdjustComposer, ValidateBuildContract), i tre file di configurazione di Rector, le tre regole Rector personalizzate e il contratto di pacchetto generato (nextpdf/backport e nextpdf/backport-pro). Va eseguito su un host di build o CI per trasformare il sorgente NextPDF moderno in una distribuzione sottoposta a downgrade. Non va mai aggiunto a un’applicazione.

Iniziare da qui: per i nuovi utenti, eseguire composer build:dry (che corrisponde a php scripts/build.php --dry-run). Esegue ogni fase in modalità di sola reportistica senza scrivere file, così da poter verificare la struttura del sorgente e i flag prima di una build effettiva. Il primo esempio di «Attività comuni» riportato di seguito mostra esattamente questo flusso.

Attività comuni

Le operazioni più frequenti con questo pacchetto sono le invocazioni di build su un host dedicato. Ogni esempio seguente è un singolo comando, verificato rispetto al sorgente di scripts/build.php e composer.json.

Convalidare la pipeline senza scrivere nulla (la prima esecuzione sicura):

composer build:dry

Corrisponde a php scripts/build.php --dry-run: esegue merge, Rector, generazione di composer, copia degli asset e convalida in modalità di sola reportistica, senza copiare nulla.

Produrre la distribuzione PHP 8.1 completa (nextpdf/backport, più nextpdf/backport-pro quando è presente il sorgente Pro):

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

Unisce il core, gli adattatori dei framework e il livello di compatibilità tcpdf, esegue il singolo passaggio di Rector per il target PHP 8.1 e scrive l’albero di pacchetti generato in ./output. Aggiungere --no-pro per saltare il pacchetto Pro.

Produrre la distribuzione PHP 7.4 solo core (la pipeline di enum a due passaggi):

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

--target=php74 forza l’output solo core e disabilita Pro, quindi esegue la pre-elaborazione degli enum, le correzioni post-Rector e il passaggio di downgrade completo a PHP 7.4.

Superfici dei comandi

Consultare questa tabella quando servono la firma esatta, i flag e il comportamento di uscita degli entrypoint di build e delle classi a livello di script che pilotano una build.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
scripts/build.php	Target, versione, percorsi di origine, percorsi di output e flag come documentato dallo script.	Utilizza valori predefiniti per il target specifici del branch.	Albero di pacchetti generato.	Uscita diversa da zero e output di errore specifico della fase.	Entrypoint principale della build. Eseguire su un host di build, non in un’applicazione.
Build::__construct(string $version, string $sourceDir, string $outputDir, string $target = 'php81', bool $includePro = true, bool $dryRun = false)	Versione, directory di origine, directory di output, corsia del runtime di destinazione, flag di inclusione di Pro, flag di dry-run.	Target PHP 8.1, Pro incluso tranne che per PHP 7.4; scrive a meno che il dry-run non sia abilitato.	Build	InvalidArgumentException per un target non supportato; errori di fase durante run().	Classe a livello di script dietro scripts/build.php.
Build::run()	nessuno.	Convalida il contratto, unisce i sorgenti, regola i metadati di composer.json ed esegue i passaggi di Rector.	bool	Restituisce false per gli errori di fase previsti; può generare eccezioni per errori imprevisti di filesystem/runtime.	La CI deve fallire quando restituisce false.
composer build:dry	Wrapper di script Composer.	Convalida della build in dry-run.	Stato di uscita e log.	Uscita diversa da zero in caso di errore di build o di convalida.	Utilizzato dai gate CI.
scripts/merge-sources.php	Percorsi di checkout del sorgente e target di merge.	Unisce i pacchetti di origine selezionati per il runtime di destinazione.	Albero del sorgente unito.	Sorgente mancante, target non supportato, errore del filesystem.	Mantenere i riferimenti del sorgente allineati al tag di rilascio.
MergeSources::__construct(string $sourceBaseDir, string $outputDir, bool $includePro = true, bool $dryRun = false, bool $coreOnly = false)	Directory di base del sorgente, directory di output, flag di inclusione di Pro, flag di dry-run, flag core-only.	Unisce tutti i repository configurati, oppure solo il core quando coreOnly è true.	MergeSources	Percorsi di origine o di output non validi durante l’esecuzione.	Classe a livello di script dietro scripts/merge-sources.php.
MergeSources::run()	nessuno.	Copia e normalizza gli alberi di sorgente selezionati nel target di build.	bool	Restituisce false per gli errori di merge previsti.	I log sono leggibili con getLog().
MergeSources::getLog()	nessuno.	Restituisce le voci di log accumulate delle fasi.	array	nessuno previsto.	Utilizzare per la diagnostica CI.
scripts/adjust-composer.php	Metadati e versione di composer.json generato.	Scrive i vincoli di pacchetto e le voci replace per l’output generato.	File composer.json regolato.	Versione non valida o file generati mancanti.	Definisce l’identità del pacchetto generato.
AdjustComposer::__construct(string $version, string $target = 'php81')	Stringa di versione e corsia di destinazione.	Target PHP 8.1.	AdjustComposer	Errori di target non valido nei percorsi di generazione.	Utilizzato dagli script di build e dai test.
AdjustComposer::generatePublicComposer()	nessuno.	Produce i metadati per nextpdf/backport.	array	nessuno previsto.	API di generazione pura per i test.
AdjustComposer::generateProComposer()	nessuno.	Produce i metadati per nextpdf/backport-pro.	array	nessuno previsto.	API di generazione pura per la corsia di build proprietaria.
AdjustComposer::writePublicComposer(string $outputDir)	Directory di output.	Scrive il composer.json pubblico generato.	void	Errori del filesystem.	Utilizzare solo nelle directory di output generate.
AdjustComposer::writeProComposer(string $proOutputDir)	Directory di output di Pro.	Scrive il composer.json Pro generato.	void	Errori del filesystem.	Richiede che l’albero di output di Pro esista.
ValidateBuildContract::__construct(string $repoRoot)	Radice del repository.	Utilizza la radice del repository fornita come base del contratto.	ValidateBuildContract	nessuno previsto.	Validatore del contratto a livello di script.
ValidateBuildContract::run()	nessuno.	Verifica gli input richiesti e i presupposti della build.	bool	Restituisce false in caso di errore del contratto.	Eseguire prima di considerare affidabile l’output della build.

Configurazione di Rector

Utilizzare questa tabella quando occorre sapere quale file di configurazione di Rector gestisce una determinata corsia di destinazione e dove si colloca ciascun passaggio nella pipeline a passaggio singolo per PHP 8.1 o a due passaggi per PHP 7.4.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
rector/config/rector-php81.php	Albero del sorgente e runtime di Rector.	Downgrade a passaggio singolo verso il target PHP 8.1.	Sorgente trasformato.	Errore di analisi o di trasformazione di Rector.	Utilizzato per la corsia di distribuzione per PHP 8.1.
rector/config/rector-php74-enums.php	Albero del sorgente e runtime di Rector.	Primo passaggio PHP 7.4 per la conversione degli enum.	Sorgente trasformato intermedio.	Errore di analisi o di trasformazione di Rector.	Viene eseguito prima del passaggio PHP 7.4 completo.
rector/config/rector-php74.php	Sorgente intermedio e runtime di Rector.	Passaggio di downgrade completo per PHP 7.4.	Sorgente compatibile con PHP 7.4.	Errore di analisi o di trasformazione di Rector.	Utilizzato per la corsia di distribuzione per PHP 7.4.

Regole personalizzate

Consultare questa tabella quando si esegue la manutenzione o l’estensione delle tre regole di Rector specifiche del progetto e occorre conoscere il contratto dei metodi di ciascuna regola e la sintassi trasformata.

Simbolo	Parametri	Comportamento predefinito	Restituisce	Genera o fallisce con	Note
DowngradeAsymmetricVisibilityRector	Proprietà o parametri promossi che utilizzano la visibilità asimmetrica.	Visibilità semplice compatibile con i runtime precedenti.	Preserva la visibilità in lettura ove possibile.	Errore della regola di Rector.	Le restrizioni dei setter sono valide solo in fase di compilazione e vengono rimosse nell’output generato.
DowngradeAsymmetricVisibilityRector::getRuleDefinition()	nessuno.	Restituisce i metadati e gli esempi della regola di Rector.	RuleDefinition	nessuno previsto.	Mantiene la documentazione della regola visibile agli strumenti di Rector.
DowngradeAsymmetricVisibilityRector::getNodeTypes()	nessuno.	Seleziona i tipi di nodo ispezionati dalla regola.	array<class-string<Node>>	nessuno previsto.	L’ambito deve restare ristretto per trasformazioni deterministiche.
DowngradeAsymmetricVisibilityRector::refactor(Node $node)	Nodo AST.	Converte la visibilità asimmetrica ove presente.	`Node	null`	Errore della regola di Rector.
DowngradeCloneWithRector	clone() con override di proprietà.	Clone più assegnazioni esplicite di proprietà.	Utilizza variabili temporanee generate.	Errore della regola di Rector.	Deve essere eseguito dopo i downgrade delle proprietà readonly.
DowngradeCloneWithRector::getRuleDefinition()	nessuno.	Restituisce i metadati e gli esempi della regola.	RuleDefinition	nessuno previsto.	Utilizzato dalla diagnostica di Rector.
DowngradeCloneWithRector::getNodeTypes()	nessuno.	Seleziona i nodi di return e di espressione.	array<class-string<Node>>	nessuno previsto.	Mantiene la regola focalizzata sulla sintassi clone-with.
DowngradeCloneWithRector::refactor(Node $node)	Nodo AST.	Riscrive clone-with in clone più assegnazioni.	`array	null`	Errore della regola di Rector.
DowngradeTraitConstantsRector	Costanti di trait e relativi riferimenti.	Proprietà statiche e riferimenti a proprietà.	Preserva la visibilità ove possibile.	Errore della regola di Rector.	Rimuove final perché le proprietà precedenti non possono essere final.
DowngradeTraitConstantsRector::getRuleDefinition()	nessuno.	Restituisce i metadati e gli esempi della regola.	RuleDefinition	nessuno previsto.	Utilizzato dalla diagnostica di Rector.
DowngradeTraitConstantsRector::getNodeTypes()	nessuno.	Seleziona i nodi di trait e di class-constant-fetch.	array<class-string<Node>>	nessuno previsto.	Mantiene la regola limitata alle costanti di trait.
DowngradeTraitConstantsRector::refactor(Node $node)	Nodo AST.	Riscrive le costanti di trait e i relativi riferimenti in proprietà compatibili.	`Node	null`	Errore della regola di Rector.

Contratto del pacchetto generato

Utilizzare questa tabella per vedere che cosa produce il builder: i nomi dei pacchetti che un progetto a valle installa effettivamente e quale di essi contiene la distribuzione Pro.

Pacchetto prodotto	Ruolo di runtime	Note
nextpdf/backport	Distribuzione di runtime open-source generata.	Sostituisce i pacchetti nextpdf/* selezionati per il runtime di destinazione.
nextpdf/backport-pro	Distribuzione Pro proprietaria generata quando è presente il sorgente Pro.	Pubblicato separatamente dal pacchetto open-source.

Note di sviluppo

• Il builder consuma i rilasci di origine e produce artefatti generati. Non modificare l’output generato come fonte di verità.
• Ogni regola personalizzata deve disporre di test con fixture prima di entrare nella pipeline di build.
• I job di rilascio devono convalidare l’output generato sul runtime di destinazione, non solo sull’host di build.