De NextPDF Backport Builder configureren

Build-gereedschap — GEEN runtime-afhankelijkheid. Alles op deze pagina configureert brontransformatie tijdens de build. Niets hiervan wordt meegeleverd naar een downstream-runtime.

In het kort

Drie Rector-configuratiebestanden in rector/config/ en drie aangepaste regels in rector/rules/ sturen de transformatie aan. De geselecteerde configuratie hangt af van het doel. Het PHP 8.1-doel gebruikt één Rector-pass. Het PHP 7.4-doel gebruikt een tweepassige pijplijn met een fix-up-fase tussen de passes. De tweede pass is vereist omdat Rector standaardwaarden van enum-cases niet in één doorloop kan herleiden.

Rector-configuraties

Bestand	Doel	Gebruikt door
rector/config/rector-php81.php	Downgrade in één pass naar PHP 8.1	PHP 8.1-doel
rector/config/rector-php74-enums.php	Pass 1 — enums omzetten naar constant-list-klassen	PHP 7.4-doel
rector/config/rector-php74.php	Pass 2 — volledige downgrade naar PHP 7.4	PHP 7.4-doel

Elke configuratie roept Rectors downgrade-set-keten aan (withDowngradeSets(php81: true) of withDowngradeSets(php74: true)) voor taalfuncties die Rector zelf afhandelt. Daarna registreert de configuratie aangepaste regels voor de overige taalfuncties. Geverifieerd aan de hand van de drie bestanden in rector/config/.

Overslaanregels

Zowel rector-php81.php als rector-php74.php slaan */tests/Benchmark/* over. De benchmarkscripts verwijzen naar externe Portable Document Format (PDF)-bibliotheken die Rector niet kan herleiden, waardoor de default-parameterresolver van Rector crasht. rector-php74.php slaat ook DowngradeHashAlgorithmXxHashRector over. Die ingebouwde regel crasht op de MHASH_XXH*-constanten die in moderne PHP verouderd zijn, en de broncode gebruikt geen xxHash. Geverifieerd aan de hand van de withSkip()-aanroepen in beide bestanden.

De drie aangepaste regels

De repository levert precies drie aangepaste Rector-regels. Alle drie zijn geregistreerd in rector-php81.php; de regels voor asymmetrische zichtbaarheid, clone-with en trait-constanten zijn ook geregistreerd in rector-php74.php. tests/Rector/RectorRulesMetadataTest.php bevestigt dit rechtstreeks door elke regel te construeren en de definitie en node-typen ervan te controleren.

DowngradeAsymmetricVisibilityRector

Deze regel verwijdert de set-modifier voor asymmetrische zichtbaarheid. Een property of gepromoveerde parameter die als public private(set) is gedeclareerd, wordt gewoon public. Leestoegang blijft behouden; de setter-beperking tijdens het compileren vervalt. Wanneer er geen leeszichtbaarheid overblijft, kiest de regel standaard voor public. Transformatie op basis van de fixture in 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

Deze regel herschrijft de functievorm clone() met een overrides-array naar een clone, expliciete property-toewijzingen en een return van een tijdelijke variabele. De teller voor tijdelijke variabelen wordt per bestand opnieuw ingesteld. Deze regel moet na de regel voor het verwijderen van readonly-properties draaien, omdat de uitgeschreven toewijzing anders zou mislukken op een readonly-property. Transformatie op basis van de fixture in 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;
    }
}

De regel heeft gedocumenteerde beperkingen. Het matchen van argumenten gebruikt een niet-recursief patroon, dus override-waarden met geneste haakjes worden niet afgehandeld. Alleen arraysleutels van het type string worden herleid tot property-namen. Geverifieerd aan de hand van rector/rules/DowngradeCloneWithRector.php en de bijbehorende fixture-suite.

DowngradeTraitConstantsRector

Deze regel zet trait-constanten om naar statische properties. Oudere runtimes weigeren trait-constanten met „Traits cannot have constants”. De regel herschrijft ook verwijzingen via self::CONST en static::CONST naar de statische-propertyvorm. Zichtbaarheid blijft behouden; de modifier final wordt verwijderd omdat properties op het oudere doel niet final kunnen zijn. Een getypeerde klasseconstante wordt een getypeerde property. Transformatie op basis van de fixture in 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;
    }
}

De tweepassige PHP 7.4-pijplijn

Het PHP 7.4-doel kan niet in één pass draaien. De resolver voor standaardparameterwaarden van Rector crasht op standaardwaarden van enum-cases bij constructorpromotie. Het buildscript draait daarom:

1. Pass 1 — enum-voorverwerking. rector-php74-enums.php draait alleen de ingebouwde regel die enums omzet naar constant-list-klassen. Na deze pass zijn enum-cases gewone klasseconstanten.
2. Cache leegmaken. De Rector-cache wordt geleegd zodat de tweede pass geen verouderde boom ziet.
3. Nabewerkingscorrecties. scripts/build.php herschrijft patronen die de enum-naar-klasseregel niet dekt. Instantiemethoden van voormalige enums worden statisch. Toegangen via EnumClass::Case->value en ->name worden herleid. Benoemde argumenten die Rector niet kon binden, worden afgevlakt tot positionele argumenten. Deze syntaxispatronen zouden anders parseerfouten veroorzaken op PHP 7.4.
4. Pass 2 — volledige downgrade. rector-php74.php draait de volledige PHP 7.4-downgrade-keten plus de aangepaste regels.

Geverifieerd aan de hand van scripts/build.php (runRector(), postProcessFixups()).

Referentie voor build-vlaggen

scripts/build.php stuurt de build aan. De opties ervan zijn geverifieerd aan de hand van de getopt()-aanroep en de Build-constructor:

Vlag	Standaard	Effect
--version=<x.y.z>	2.0.0	Versie die naar de gegenereerde composer.json en CHANGELOG.md wordt geschreven
--source-dir=<path>	c:/Users/admin/Documents	Root die de naastgelegen bronrepository’s bevat
--output-dir=<path>	<repo>/output	Waar de gegenereerde distributie wordt geschreven
--target=php74 | --target=php81	php81	Downgrade-doel. php74 dwingt core-only af en schakelt Pro uit
--dry-run	uit	Voert elke fase uit in report-only-modus; kopieën en Rector worden overgeslagen
--no-pro	uit	Sluit het Pro-pakket uit (alleen voor het PHP 8.1-doel; PHP 7.4 sluit het al uit)

Een ongeldige --target-waarde werpt InvalidArgumentException op voordat er werk begint. Geverifieerd aan de hand van Build::__construct() (VALID_TARGETS-bewaking).

Composer-scripts

Script	Commando	Doel
composer test	phpunit	Voert de fixture-suites van de regels uit
composer analyse	phpstan analyse rector/rules scripts --level=10	Voert statische analyse uit op de buildcode
composer build	php scripts/build.php	Volledige build
composer build:dry	php scripts/build.php --dry-run	Dry-run-build

Geverifieerd aan de hand van composer.jsonscripts.

Volgende

• /integrations/backport/quickstart/ — voer de dry-run en de volledige build uit.
• /integrations/backport/troubleshooting/ — wat elke mislukte fase betekent.