Rector

A Rector PHP-kódot ír át automatikusan. Szabályok alapján frissíti a régi szintaxist újabb PHP-verzióra, törli a holt kódot, és típusokat ad a tulajdonságokhoz és függvényekhez. WordPress-fejlesztésben akkor jön jól, ha egy régi bővítmény vagy téma kódját kell felhozni a mai PHP-hez, és kézzel túl sok fájl lenne.

A Rector nem elemez, hanem módosít. A hibák kereséséhez használd a PHPStant, a Rectort pedig a kód átírására.

Telepítés

Fejlesztői függőségként telepítsd Composerrel. A Rector doksija szerint PHP 7.2 vagy újabb kell hozzá, de PHP 5.x és 8.x kódot is át tud írni.

Terminál

composer require rector/rector --dev

Bedrock vagy más Composeres projekt esetén a Composer cikk írja le az alapokat. Bedrock-projektben a Bedrock cikk mutatja a szerkezetet; a withPaths()-ban csak a saját bővítményed vagy témád mappáját add meg.

Beállítás

Az első futtatáskor a Rector felajánlja a rector.php létrehozását:

Terminál

vendor/bin/rector

A kérdésre („No “rector.php” config found. Should we generate it for you?”) válaszolj igennel. A fájlban add meg, mely mappákat kezelje:

rector.php

<?php

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/inc',
        __DIR__ . '/my-plugin.php',
    ])
    ->withPhpSets();

A withPhpSets() argumentum nélkül a composer.json-ban megadott PHP-verziót veszi alapul, a doksi ezt tartja a bevált megoldásnak.

A tisztítóhalmazokat a withPreparedSets() kapcsolja be:

rector.php

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/inc'])
    ->withPhpSets()
    ->withPreparedSets(
        deadCode: true,
        codeQuality: true,
    );

A doksi további kapcsolókat is felsorol: codingStyle, naming, privatization, typeDeclarations. A típusok fokozatos bevezetéséhez van a withTypeCoverageLevel(), a doksi példája 0-ról indul. A doksi azt tanácsolja, hogy kezdd kicsiben, egyszerre egy szinttel, hogy az első pull request könnyen áttekinthető legyen.

Amit ki akarsz hagyni, azt a withSkip() kezeli:

rector.php

->withSkip([
    __DIR__ . '/inc/vendor-lib',
    '*/*.generated.php',
])

A withSkip() abszolút útvonalat, egy fájlt vagy * jeles maszkot fogad el.

Futtatás: először mindig dry-run

A --dry-run kapcsoló csak kiírja a változtatásokat, a fájlokhoz nem nyúl:

Terminál

vendor/bin/rector process --dry-run

Ha a kimenet rendben van, futtasd éles módban:

Terminál

vendor/bin/rector process

Néhány hasznos kapcsoló a CLI-opciók doksijából:

Kapcsoló	Mit csinál
--dry-run, -n	a diffet mutatja, a fájlokat nem módosítja
--only=RULE	egyetlen szabályt futtat a konfigból
--max-changes=N	N változtatás után leáll
--php	csak a PHP-frissítő szabályokat futtatja
--clear-cache	futás előtt törli a gyorsítótárat
--debug	részletes hibakimenet, kikapcsolja a párhuzamos futást

A teljes listát a vendor/bin/rector process --help adja.

Régi WordPress-kód frissítése

Egy régi bővítmény vagy téma átalakítása biztonságosan így megy:

1. Commitold a jelenlegi állapotot Gitben, tiszta munkafával indulj.
2. Állítsd be a composer.json-ban a PHP-verziót, amelyet a bővítmény támogatni fog.
3. Vedd fel a withPhpSets()-et, és futtasd --dry-run módban.
4. Nézd át a diffet, majd futtasd éles módban.
5. Futtasd a teszteket (PHPUnit) és a PHPStant, nézd át a Git diffet, és csak ezután commitolj.
6. Következő körben jöhet a withPreparedSets(), majd a típusszint emelése.

WordPress-specifikus szabálykészlet

A Rector saját doksija a WordPressről nem ír. Van viszont egy külső, nyílt forrású csomag, az fsylum/rector-wordpress (MIT licenc), amely WordPress-frissítő szabályokat ad a Rectorhoz. A README szerint PHP 8.2 vagy újabb és Rector 2.0 vagy újabb kell hozzá.

Terminál

composer require fsylum/rector-wordpress --dev

A README példája egy kiválasztott WordPress-verzióig alkalmazza az összes szabályt:

rector.php

use Fsylum\RectorWordPress\Set\WordPressLevelSetList;
use Rector\Config\RectorConfig;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->sets([
        WordPressLevelSetList::UP_TO_WP_7_0,
    ]);
};

Egy adott verzió szabályait a WordPressSetList::WP_7_0 típusú konstansok adják. Ez nem a Rector hivatalos csomagja, ezért a szabályait is ugyanúgy nézd át dry-runnal, mint a többit.

Mire figyelj

• Mindig dry-run és Git. A Rector a fájlokat írja át. Futtatás előtt legyen tiszta commit, hogy a változtatást egy paranccsal visszavonhasd.
• A tesztek nem opcionálisak. Az átírt kód működését a Rector nem garantálja, a tesztek és a PHPStan futtatása a te dolgod.
• Csak a saját kódot add meg. A vendor mappát és a külső könyvtárakat hagyd ki a withPaths()-ból vagy a withSkip()-ből.
• Ne éles szerveren futtasd. A Rector fejlesztői eszköz: a fejlesztői gépen futtasd, az eredményt Gitből telepítsd.
• Kis lépésekben haladj. Egy szabálycsoport, egy commit, így a hibás átírást is könnyű megtalálni.

Hasznos linkek

• Rector dokumentáció
• Rector: set listák
• Rector: CLI-opciók
• Rector a GitHubon
• fsylum/rector-wordpress