NextPDF Backport Builder konfigurieren

Build-Werkzeug – KEINE Laufzeitabhängigkeit. Alle Einstellungen auf dieser Seite steuern, wie der Quellcode zur Build-Zeit transformiert wird. Nichts davon wird an eine nachgelagerte Laufzeit ausgeliefert.

Auf einen Blick

Die Transformation wird von drei Rector-Konfigurationsdateien unter rector/config/ und drei eigenen Regeln unter rector/rules/ gesteuert. Welche Konfiguration zum Einsatz kommt, hängt vom Ziel ab. Für das PHP-8.1-Ziel genügt ein einzelner Rector-Durchlauf. Das PHP-7.4-Ziel verwendet eine zweistufige Pipeline mit einer zwischengeschalteten Fix-up-Stufe. Der zweite Durchlauf ist erforderlich, weil Rector die Standardwerte von Enum-Fällen nicht in einem einzigen Durchlauf auflösen kann.

Rector-Konfigurationen

Datei	Zweck	Verwendet von
rector/config/rector-php81.php	Einstufiges Downgrade auf PHP 8.1	PHP-8.1-Ziel
rector/config/rector-php74-enums.php	Durchlauf 1 – Enums in Konstantenlistenklassen umwandeln	PHP-7.4-Ziel
rector/config/rector-php74.php	Durchlauf 2 – vollständiges Downgrade auf PHP 7.4	PHP-7.4-Ziel

Jede Konfiguration ruft Rectors Downgrade-Set-Kette auf (withDowngradeSets(php81: true) oder withDowngradeSets(php74: true)), um die Sprachfeatures abzudecken, die Rector von Haus aus verarbeitet. Anschließend registriert sie die eigenen Regeln für die Features, die Rector nicht behandelt. Dies ist anhand der drei Dateien in rector/config/ verifiziert.

Skip-Regeln

Die Konfigurationen rector-php81.php und rector-php74.php überspringen jeweils */tests/Benchmark/*. Die Benchmark-Skripte referenzieren externe PDF-Bibliotheken, die Rector nicht auflösen kann; dadurch stürzt sein Standardparameter-Resolver ab. rector-php74.php überspringt zusätzlich DowngradeHashAlgorithmXxHashRector. Diese eingebaute Regel stürzt an den in modernem PHP veralteten MHASH_XXH*-Konstanten ab, und der Quellcode verwendet kein xxHash. Dies ist anhand der withSkip()-Aufrufe in beiden Dateien verifiziert.

Die drei eigenen Regeln

Das Repository liefert genau drei eigene Rector-Regeln. Alle drei sind in rector-php81.php registriert; die Regeln für asymmetrische Sichtbarkeit, clone-with und Trait-Konstanten sind außerdem in rector-php74.php registriert. Dies wird direkt durch tests/Rector/RectorRulesMetadataTest.php abgesichert, das jede Regel konstruiert und ihre Definition sowie Knotentypen prüft.

DowngradeAsymmetricVisibilityRector

Entfernt den Set-Modifizierer für asymmetrische Sichtbarkeit. Eine Eigenschaft oder ein geförderter Parameter, der als public private(set) deklariert ist, wird zu einfachem public. Der Lesezugriff bleibt erhalten; die Setter-Beschränkung entfällt bei der Übersetzung. Wenn keine Lesesichtbarkeit verbleibt, fällt die Regel auf public zurück. Quellcodegestützte Transformation aus 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

Schreibt die Funktionsform clone() mit einem Overrides-Array in ein Klonen mit anschließenden expliziten Eigenschaftszuweisungen und der Rückgabe einer temporären Variablen um. Der Zähler für temporäre Variablen wird pro Datei zurückgesetzt. Diese Regel muss nach der Regel zum Entfernen von readonly-Eigenschaften laufen, da die expandierte Zuweisung sonst an einer readonly-Eigenschaft fehlschlagen würde. Quellcodegestützte Transformation aus 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;
    }
}

Die Regel hat dokumentierte Einschränkungen. Der Argumentabgleich verwendet ein nicht rekursives Muster, sodass Override-Werte mit verschachtelten Klammern nicht behandelt werden. Nur String-Array-Schlüssel werden zu Eigenschaftsnamen aufgelöst. Dies ist anhand von rector/rules/DowngradeCloneWithRector.php und seiner Fixture-Suite verifiziert.

DowngradeTraitConstantsRector

Wandelt Trait-Konstanten in statische Eigenschaften um. Eine Trait-Konstante ist ein Sprachfeature, das ältere Laufzeiten mit „Traits cannot have constants” ablehnen. Die Regel schreibt außerdem self::CONST- und static::CONST-Referenzen in statische Eigenschaftszugriffe um. Die Sichtbarkeit bleibt erhalten; der Modifizierer final wird entfernt, da Eigenschaften auf dem älteren Ziel nicht final sein können. Eine typisierte Klassenkonstante wird zu einer typisierten Eigenschaft. Quellcodegestützte Transformation aus 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;
    }
}

Die zweistufige PHP-7.4-Pipeline

Das PHP-7.4-Ziel kann nicht in einem einzigen Durchlauf verarbeitet werden. Rectors Resolver für Standardparameterwerte stürzt an Enum-Fall-Standardwerten in der Konstruktor-Förderung ab. Das Build-Skript führt daher Folgendes aus:

1. Durchlauf 1 – Enum-Vorverarbeitung. rector-php74-enums.php führt nur die eingebaute Regel zur Umwandlung von Enums in Konstantenlistenklassen aus. Nach diesem Durchlauf liegen Enum-Fälle als einfache Klassenkonstanten vor.
2. Cache leeren. Der Rector-Cache wird geleert, damit der zweite Durchlauf keinen veralteten Baum sieht.
3. Nachbearbeitungs-Fix-ups. scripts/build.php schreibt Muster um, die von der Enum-zu-Klasse-Regel nicht abgedeckt werden. Frühere Enum-Instanzmethoden werden statisch. EnumClass::Case->value- und ->name-Zugriffe werden aufgelöst. Benannte Argumente, die Rector nicht binden konnte, werden zu positionsbasierten Argumenten umgeschrieben. Diese Syntaxmuster würden unter PHP 7.4 sonst Parse-Fehler auslösen.
4. Durchlauf 2 – vollständiges Downgrade. rector-php74.php führt die vollständige PHP-7.4-Downgrade-Kette plus die eigenen Regeln aus.

Verifiziert anhand von scripts/build.php (runRector(), postProcessFixups()).

Referenz der Build-Flags

scripts/build.php ist der Orchestrator. Seine Optionen sind anhand des getopt()-Aufrufs und des Build-Konstruktors verifiziert:

Flag	Standard	Wirkung
--version=<x.y.z>	2.0.0	Version, die in die generierte composer.json und CHANGELOG.md geschrieben wird
--source-dir=<path>	c:/Users/admin/Documents	Wurzelverzeichnis, das die benachbarten Quell-Repositorys enthält
--output-dir=<path>	<repo>/output	Zielverzeichnis, in das die generierte Distribution geschrieben wird
--target=php74 | --target=php81	php81	Downgrade-Ziel. php74 erzwingt Core-only und deaktiviert Pro
--dry-run	aus	Jede Stufe im Nur-Bericht-Modus ausführen; Kopiervorgänge und Rector werden übersprungen
--no-pro	aus	Das Pro-Paket ausschließen (nur PHP-8.1-Ziel; PHP 7.4 schließt es bereits aus)

Ein ungültiger --target-Wert löst eine InvalidArgumentException aus, bevor eine Verarbeitung beginnt. Dies ist anhand von Build::__construct() (VALID_TARGETS-Guard) verifiziert.

Composer-Skripte

Skript	Befehl	Zweck
composer test	phpunit	Die Fixture-Suiten der Regeln ausführen
composer analyse	phpstan analyse rector/rules scripts --level=10	Den Build-Code statisch analysieren
composer build	php scripts/build.php	Vollständiger Build
composer build:dry	php scripts/build.php --dry-run	Dry-Run-Build

Verifiziert anhand von composer.jsonscripts.

Weiter

• /integrations/backport/quickstart/ – den Dry-Run und den vollständigen Build ausführen.
• /integrations/backport/troubleshooting/ – was die einzelnen Fehlerstufen bedeuten.