# Rector

> A Rector automatikusan átírja a PHP-kódot: telepítés Composerrel, rector.php beállítás, dry-run és a régi WordPress-kód frissítése.

A [Rector](https://getrector.com/) 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](https://hub.hellowp.io/hu/knowledge-base/developer-tools/phpstan/), 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.

```bash title="Terminál"
composer require rector/rector --dev
```

Bedrock vagy más Composeres projekt esetén a [Composer](https://hub.hellowp.io/hu/knowledge-base/developer-tools/composer/) cikk írja le az alapokat.  Bedrock-projektben a [Bedrock](https://hub.hellowp.io/hu/knowledge-base/developer-tools/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:

```bash title="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:

```php title="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:

```php title="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:

```php title="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:

```bash title="Terminál"
vendor/bin/rector process --dry-run
```

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

```bash title="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](https://hub.hellowp.io/hu/knowledge-base/developer-tools/phpunit/)) és a [PHPStant](https://hub.hellowp.io/hu/knowledge-base/developer-tools/phpstan/), 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](https://github.com/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á.

```bash title="Terminál"
composer require fsylum/rector-wordpress --dev
```

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

```php title="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ó](https://getrector.com/documentation)
- [Rector: set listák](https://getrector.com/documentation/set-lists)
- [Rector: CLI-opciók](https://getrector.com/documentation/cli-options)
- [Rector a GitHubon](https://github.com/rectorphp/rector)
- [fsylum/rector-wordpress](https://github.com/fsylum/rector-wordpress)