Configurazione del Backport Builder di NextPDF

Strumenti di build — NON una dipendenza di runtime. Quanto descritto in questa pagina configura il modo in cui il sorgente viene trasformato in fase di build. Nulla di tutto ciò viene distribuito a un runtime a valle.

In sintesi

La trasformazione è controllata da tre file di configurazione di Rector in rector/config/ e da tre regole personalizzate in rector/rules/. La configurazione selezionata dipende dal target. Il target PHP 8.1 richiede un singolo passaggio di Rector. Il target PHP 7.4 usa una pipeline a due passaggi con una fase di correzione intermedia. Il secondo passaggio è necessario perché Rector non riesce a risolvere i valori predefiniti dei casi di enum in un’unica traversata.

Configurazioni di Rector

File	Scopo	Usato da
rector/config/rector-php81.php	Downgrade a passaggio singolo verso PHP 8.1	Target PHP 8.1
rector/config/rector-php74-enums.php	Passaggio 1 — converte gli enum in classi con elenco di costanti	Target PHP 7.4
rector/config/rector-php74.php	Passaggio 2 — downgrade completo a PHP 7.4	Target PHP 7.4

Ogni configurazione richiama la catena di set di downgrade di Rector (withDowngradeSets(php81: true) o withDowngradeSets(php74: true)) per le funzionalità che Rector gestisce in modo nativo. Registra quindi le regole personalizzate per le funzionalità non gestite. Verificato sui tre file in rector/config/.

Regole di esclusione

rector-php81.php e rector-php74.php escludono entrambi */tests/Benchmark/*. Gli script di benchmark fanno riferimento a librerie PDF esterne che Rector non riesce a risolvere, causando il crash del suo risolutore dei parametri predefiniti. rector-php74.php esclude inoltre DowngradeHashAlgorithmXxHashRector. Quella regola integrata va in crash sulle costanti MHASH_XXH* deprecate nelle versioni moderne di PHP, e il sorgente non usa xxHash. Verificato sulle chiamate withSkip() in entrambi i file.

Le tre regole personalizzate

Il repository fornisce esattamente tre regole personalizzate di Rector. Tutte e tre sono registrate in rector-php81.php; le regole per la visibilità asimmetrica, per clone-with e per le costanti di trait sono registrate anche in rector-php74.php. Il dato è verificato direttamente da tests/Rector/RectorRulesMetadataTest.php, che costruisce ciascuna regola e ne controlla la definizione e i tipi di nodo.

DowngradeAsymmetricVisibilityRector

Rimuove il modificatore set della visibilità asimmetrica. Una proprietà o un parametro promosso dichiarato public private(set) diventa semplicemente public. L’accesso in lettura viene preservato; la restrizione sul setter applicata in compilazione viene eliminata. Se non rimane alcuna visibilità in lettura, la regola usa per impostazione predefinita public. Trasformazione basata sul sorgente, da tests/Rector/Fixtures/DowngradeAsymmetricVisibility/public_private_set.php.inc:

before

<?php

class Config {
    public private(set) float $x = 0.0;
    public private(set) string $name = '';
    public private(set) int $count = 0;
}

after

<?php

class Config {
    public float $x = 0.0;
    public string $name = '';
    public int $count = 0;
}

DowngradeCloneWithRector

Riscrive la forma funzionale clone() con un array di override in un clone seguito da assegnazioni esplicite di proprietà e dal ritorno di una variabile temporanea. Il contatore della variabile temporanea si azzera per ogni file. Questa regola deve essere eseguita dopo la regola che rimuove le proprietà readonly, perché altrimenti l’assegnazione espansa fallirebbe contro una proprietà readonly. Trasformazione basata sul sorgente, da tests/Rector/Fixtures/DowngradeCloneWith/return_clone_with.php.inc:

before

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self {
        return clone($this, ['width' => $width, 'height' => $height]);
    }
}

after

<?php

class PageSize {
    public float $width = 0.0;
    public float $height = 0.0;

    public function withDimensions(float $width, float $height): self
    {
        $__cloneResult1 = clone $this;
        $__cloneResult1->width = $width;
        $__cloneResult1->height = $height;
        return $__cloneResult1;
    }
}

La regola presenta limitazioni documentate. Il confronto degli argomenti utilizza un pattern non ricorsivo, quindi i valori di override che contengono parentesi annidate non vengono gestiti. Vengono risolte in nomi di proprietà solo le chiavi di array di tipo stringa. Verificato su rector/rules/DowngradeCloneWithRector.php e sulla relativa suite di fixture.

DowngradeTraitConstantsRector

Converte le costanti di trait in proprietà statiche. Una costante di trait è una funzionalità che i runtime più datati rifiutano con “Traits cannot have constants”. La regola riscrive inoltre i riferimenti self::CONST e static::CONST nella forma di proprietà statica. La visibilità viene preservata; il modificatore final viene rimosso perché le proprietà non possono essere final nel target più datato. Una costante di classe tipizzata diventa una proprietà tipizzata. Trasformazione basata sul sorgente, da tests/Rector/Fixtures/DowngradeTraitConstants/private_constant.php.inc:

before

<?php

trait HasLimit
{
    private const MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::MAX_SIZE;
    }
}

after

<?php

trait HasLimit
{
    private static $MAX_SIZE = 1024;

    public function getLimit(): int
    {
        return self::$MAX_SIZE;
    }
}

La pipeline a due passaggi per PHP 7.4

Il target PHP 7.4 non può essere generato in un singolo passaggio. Il risolutore dei valori predefiniti dei parametri di Rector va in crash sui valori predefiniti dei casi di enum nella promozione del costruttore. Lo script di build esegue pertanto:

1. Passaggio 1 — pre-elaborazione degli enum. rector-php74-enums.php esegue solo la regola integrata di conversione da enum a classe con elenco di costanti. Dopo questo passaggio, i casi di enum diventano semplici costanti di classe.
2. Svuotamento della cache. La cache di Rector viene svuotata in modo che il secondo passaggio non veda un albero non aggiornato.
3. Correzioni di post-elaborazione. scripts/build.php riscrive i pattern che la regola da enum a classe non copre. I precedenti metodi di istanza degli enum diventano statici. Gli accessi EnumClass::Case->value e ->name vengono risolti. Gli argomenti con nome che Rector non è riuscito ad associare vengono appiattiti in argomenti posizionali. Si tratta di pattern sintattici che altrimenti causerebbero un errore di parsing su PHP 7.4.
4. Passaggio 2 — downgrade completo. rector-php74.php esegue l’intera catena di downgrade per PHP 7.4 più le regole personalizzate.

Verificato su scripts/build.php (runRector(), postProcessFixups()).

Riferimento dei flag di build

scripts/build.php è l’orchestratore. Le opzioni, verificate sulla chiamata getopt() e sul costruttore Build, sono:

Flag	Predefinito	Effetto
--version=<x.y.z>	2.0.0	Versione scritta nei file composer.json e CHANGELOG.md generati
--source-dir=<path>	c:/Users/admin/Documents	Root che contiene i repository sorgente affiancati
--output-dir=<path>	<repo>/output	Dove viene scritta la distribuzione generata
--target=php74 | --target=php81	php81	Target di downgrade. php74 forza solo il core e disabilita Pro
--dry-run	off	Esegue ogni fase in modalità di sola reportistica; le copie e Rector vengono saltate
--no-pro	off	Esclude il pacchetto Pro (solo per il target PHP 8.1; PHP 7.4 lo esclude già)

Un valore --target non valido solleva InvalidArgumentException prima che inizi qualsiasi lavoro. Verificato su Build::__construct() (controllo VALID_TARGETS).

Script Composer

Script	Comando	Scopo
composer test	phpunit	Esegue le suite di fixture delle regole
composer analyse	phpstan analyse rector/rules scripts --level=10	Analizza staticamente il codice di build
composer build	php scripts/build.php	Build completa
composer build:dry	php scripts/build.php --dry-run	Build in dry-run

Verificato su composer.jsonscripts.

Avanti

• /integrations/backport/quickstart/ — eseguire il dry-run e la build completa.
• /integrations/backport/troubleshooting/ — significato di ogni fase di errore.