Risoluzione dei problemi di NextPDF Backport Builder

Strumenti di build — NON una dipendenza di runtime. Ogni sintomo descritto in questa pagina riguarda una condizione che si verifica durante la build su un host di manutenzione o di CI. Nessuna di queste condizioni si manifesta in un’applicazione a valle.

In breve

La build esegue cinque fasi ordinate. Si arresta al primo errore e stampa il nome della fase insieme al messaggio. Leggere la fase, quindi individuare la causa qui sotto. Le fasi sono: unione delle sorgenti, esecuzione del downgrade con Rector, generazione di composer.json, copia degli asset statici e convalida dell’output. Verificato rispetto a scripts/build.php (run() e step()).

Fase: unione delle sorgenti

”Source repo '' not found at: ”

La fase di unione convalida ogni repository sorgente atteso prima della copia. Si interrompe indicando il nome e il percorso del repository mancante. Il target PHP 8.1 prevede nextpdf, nextpdf-Artisan, nextpdf-compat-legacy, nextpdf-Laravel, nextpdf-Symfony, nextpdf-CodeIgniter e — quando Pro è incluso — nextpdf-Pro. Il target PHP 7.4 prevede solo nextpdf. Verificato rispetto a scripts/merge-sources.php (ciclo di convalida di run(), mappa dei repository in __construct()).

Risoluzione: eseguire il checkout dei repository come directory sorelle sotto il percorso passato a --source-dir, usando i nomi di directory esatti indicati sopra. Un’esecuzione di prova (dry-run) elenca ogni repository che verrebbe letto. Usarla per confermare il layout prima di una build completa.

Fase: esecuzione del downgrade con Rector

Rector termina con codice diverso da zero

L’orchestratore segnala Rector failed on <label> (exit code: N) e si arresta. L’etichetta indica quale passaggio è fallito: public package, pro package, enum pre-processing o full downgrade. Verificato rispetto a scripts/build.php (runRectorPass()).

Crash del resolver dei parametri predefiniti sui default enum (PHP 7.4)

Questo è il motivo per cui il target PHP 7.4 usa due passaggi. Il resolver dei valori dei parametri predefiniti di Rector va in crash su un caso enum usato come valore predefinito di una promozione del costruttore. Il passaggio 1 (rector-php74-enums.php) converte prima gli enum in classi con elenchi di costanti. Il passaggio completo del passaggio 2 non incontra quindi mai un valore predefinito basato su un caso enum. Se si aggira l’orchestratore e si esegue la configurazione PHP 7.4 completa direttamente su sorgenti contenenti enum, questo crash è da attendersi. Verificato rispetto a scripts/build.php (commento di runRector() e sequenza a due passaggi) e rector/config/rector-php74-enums.php.

Gli script di benchmark causano il crash di Rector

rector-php81.php e rector-php74.php escludono */tests/Benchmark/*. Quegli script fanno riferimento a librerie PDF esterne che Rector non riesce a risolvere, causando il crash del resolver dei parametri predefiniti. Se un percorso di benchmark viene elaborato, il glob di esclusione manca oppure il percorso è diverso. Verificato rispetto alle chiamate withSkip().

Crash di MHASH_XXH* (PHP 7.4)

rector-php74.php esclude DowngradeHashAlgorithmXxHashRector. Quella regola integrata va in crash quando incontra le costanti xxHash. Il codice sorgente non usa xxHash, quindi l’esclusione è sicura. Verificato rispetto a rector/config/rector-php74.php (withSkip()).

Fase: correzioni post-Rector (solo PHP 7.4)

Le correzioni vengono eseguite tra i due passaggi. Riscrivono i pattern che la regola di conversione da enum a classe lascia nell’output. Se l’output PHP 7.4 presenta un errore di parsing che coinvolge EnumClass::Case->value, ->name, un ex metodo enum chiamato come metodo di istanza oppure un argomento con nome su un tipo non risolto, significa che la correzione non ha trovato corrispondenza con quel pattern. Anche la limitazione di clone-with si applica qui: la corrispondenza degli argomenti non è ricorsiva, quindi un valore di override con parentesi annidate non viene riscritto. Verificato rispetto a scripts/build.php (postProcessFixups(), fixEnumMethodCallSites(), applyFixups()) e rector/rules/DowngradeCloneWithRector.php (limitazione documentata).

Fase: generazione di composer.json

Questa fase sposta le directory elaborate src/ e tests/ dalla directory temporanea di build alla directory di output. Poi scrive il composer.json generato. Un errore a questo punto è quasi sempre una condizione del filesystem: la directory di output non è scrivibile oppure l’albero temporaneo di build è assente perché Rector non ha prodotto nulla. Verificato rispetto a scripts/build.php (adjustComposer(), moveTree()).

Fase: copia degli asset statici

Questa fase copia LICENSE dal repository sorgente del core e scrive un CHANGELOG.md generato. Quando la licenza è assente, la copia viene saltata silenziosamente e la build prosegue; il changelog viene sempre scritto. Un errore a questo punto indica che la directory di output è diventata non scrivibile durante la build. Verificato rispetto a scripts/build.php (copyStaticAssets()).

Fase: convalida dell’output

”Output src/ directory not found” / “No PHP files found in output”

La convalida richiede una directory output/src non vuota. Un albero vuoto significa che l’unione non ha copiato nulla oppure che lo spostamento dei file è fallito. Verificato rispetto a scripts/build.php (validateOutput()).

”Syntax validation: skipped (requires PHP runtime)”

Questo è il comportamento previsto, non un errore. L’host di build esegue un PHP moderno, non quello del target, quindi la fase locale si limita a contare i file e a stampare il comando Docker per un controllo di sintassi effettivo. Il controllo di sintassi autorevole è il passaggio php -l post-build nel workflow di rilascio, eseguito sul runtime effettivo del target. Verificato rispetto a scripts/build.php (validateOutput()) e .github/workflows/build.yml (i passaggi di controllo sintassi PHP 8.1 / PHP 7.4).

Limitazioni note

Queste limitazioni sono intrinseche all’approccio di downgrade. Sono verificate rispetto alle regole e alla sezione «Known Limitations» del README.md del progetto:

• Le proprietà readonly vengono rimosse. readonly viene rimosso affinché l’assegnazione esplicita delle proprietà generata dall’espansione di clone-with sia legale sul runtime più datato. L’immutabilità non è più imposta dal runtime nell’output sottoposto a downgrade.
• #[Override] non viene imposto su PHP 8.1. L’attributo può rimanere, ma il runtime più datato non agisce su di esso.
• Il target PHP 7.4 è solo core. Gli adapter per i framework, il livello di compatibilità tcpdf e Pro non fanno parte della distribuzione PHP 7.4, dato il modo in cui è costruito lo script di build.
• Pro è un pacchetto separato e solo per PHP 8.1. Non esiste una build Pro per PHP 7.4.
• La corrispondenza degli argomenti di clone-with non è ricorsiva. I valori di override che contengono parentesi annidate non vengono trasformati e solo le chiavi di array di tipo stringa vengono risolte in nomi di proprietà.

Passaggi successivi

• /integrations/backport/configuration/ — il riferimento per regole e flag.
• /integrations/backport/production-usage/ — il gate CI e i canali di rilascio.