Rector on ララジャパン

Rectorでリファクタリングを自動化　その３

Sun, 04 Aug 2024 06:58:49 +0900

以前にリファクタリングを自動化できるツール、Rectorを紹介しました。前回の記事ではRector側で用意された変換ルールに則ってリファクタする方法をお伝えしました。しかし、Rectorの真骨頂はむしろ自分で変換ルールを作成して各々の環境に合わせて自由にカスタマイズ出来る点にあります。直近の実務でそちらに触れる機会がありましたのでご紹介致します。

Rectorのインストール(おさらい）

前回の記事からだいぶ時間が経ってしまったのでプロジェクトにrectorをセットアップする手順からおさらいします。まず、以下でrectorをプロジェクトにinstallして下さい。

$ composer require rector/rector --dev

2024/08/03時点でversion 1.2.1がinstallされました。次に、初回実行して設定ファイルを作成します。

$ vendor/bin/rector

 No "rector.php" config found. Should we generate it for you? [yes]:
 > yes

rector.phpがルートディレクトリに作成されました。そちらの編集については後ほど解説致します。

自作ルールでリファクタリングを自動化

例えば、直近で私が携わった案件ではそれまで定数で管理していた値をPHP8.1の導入と共にEnumへ切り替えるリファクタをRectorで自作ルールを作成して行いました。今回はそちらのケースを例として紹介します。

定数をEnumに変換する

以下の様なモデルクラスがあったとします。

app/Models/Order.php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Factories\HasFactory;

class Order extends Model
{
    use HasFactory;

    // order status constants
    const ORDER_STATUS_ORDERED = 0;
    const ORDER_STATUS_SHIPPED = 1;
    const ORDER_STATUS_CANCELED = 2;

    protected $table = 'order';

    protected $primaryKey = 'order_id';

    protected $guarded = ['order_id', 'created_at', 'updated_at'];

    // キャンセルされた？
    public function isCanceled()
    {
        return $this->status === self::ORDER_STATUS_CANCELED;
    }

    // 売上として計上された注文
    public function scopeAsRevenue($query)
    {
        return $query->whereIn('status', [self::ORDER_STATUS_ORDERED, self::ORDER_STATUS_SHIPPED]);
    }

}

このクラスではorder_statusというプロパティの値を定数で管理しています。そして、それらを以下のOrderStatusというEnumに切り替えたいとします。

app/Enums/OrderStatus.php

namespace App\Enums;

enum OrderStatus: int
{
    case ORDERED = 1;
    case SHIPPED = 2;
    case CANCELED = 3;
}

具体的にはコードを以下の様に書き換えます。

self::ORDER_STATUS_CANCELED
↓
OrderStatus::CANCELED->value

カスタムルール作成

こちらの公式ドキュメントを参考に進めます。まず、カスタムルールを定義するクラスを作成します。

$ vendor/bin/rector custom-rule

// 作成するカスタムルール名を指定（ReplaceConstantToEnumValueとしました）
What is the name of the rule class (e.g. "LegacyCallToDbalMethodCall")?:
> ReplaceConstantToEnumValue

Generated files
===============

* utils/rector/tests/Rector/ReplaceConstantToEnumValueRector/Fixture/some_class.php.inc
* utils/rector/tests/Rector/ReplaceConstantToEnumValueRector/config/configured_rule.php
* utils/rector/src/Rector/ReplaceConstantToEnumValueRector.php
* utils/rector/tests/Rector/ReplaceConstantToEnumValueRector/ReplaceConstantToEnumValueRectorTest.php

[OK] Base for the "ReplaceConstantToEnumValueRector" rule was created. Now you can fill the missing parts

[OK] We also update composer.json autoload-dev, to load Rector rules. Now run "composer
dump-autoload" to update paths

[OK] We also update /***/rector/phpunit.xml, to add a rector test suite.
You can run the rector tests by running: phpunit --testsuite rector

実行が完了するとルートディレクトリにutilsディレクトリが作成されます。utilsディレクトリの構造は以下の様になっているはずです。

$ tree utils

utils
└── rector
    ├── src
    │   └── Rector
    │       └── ReplaceConstantToEnumValueRector.php
    └── tests
        └── Rector
            └── ReplaceConstantToEnumValueRector
                ├── ReplaceConstantToEnumValueRectorTest.php
                ├── Fixture
                │   └── some_class.php.inc
                └── config
                    └── configured_rule.php

composer.jsonにutils配下のクラスをオートロードする設定が追加されていますので反映させておきましょう。

$ composer dump-autoload

カスタムルールを定義

作成されたReplaceConstantToEnumValueRector.phpを編集してカスタムルールを定義していきましょう。このクラスにはデフォルトで３つのメソッドが定義されています。

getRuleDefinition()
getNodeTypes()
refactor()

１つずつ解説します。

getRuleDefinition()

こちらのメソッドではリファクタの前後でコードがどの様に変更されるか、を定義します。こちらのメソッドは他の開発者がルールを理解しやすくする為です。また、ドキュメントを作成する際に使える様ですが、そちらはまだ深掘りしていないので今回は割愛します。getRuleDefinition()は以下の様に実装しました。

utils/rector/src/Rector/ReplaceConstantToEnumValueRector.php

...
    public function getRuleDefinition(): RuleDefinition
    {
        return new RuleDefinition('Replace Constant to Enum', [
            new CodeSample(
                // BEFORE
                <<<'CODE_SAMPLE'
ORDER_STATUS_ORDERED
CODE_SAMPLE
                ,
                // AFTER
                <<<'CODE_SAMPLE'
OrderStatus::ORDERED->value
CODE_SAMPLE
            ),
        ]);
...

getNodeTypes()

こちらはリファクタの対象となるnodeを指定するメソッドです。nodeとはソースコードの構成要素の事で、クラスやメソッド、変数、条件式などです。Rectorはソースコードをnodeから成るツリー構造（AST）として解析し、nodeを操作する事でコードを変換しています。指定可能なnodeはこちらにまとめられています。例えば、今回は定数を操作したいのでClassConstFetch::classを指定します。

utils/rector/src/Rector/ReplaceConstantToEnumValueRector.php

...
    /**
     * @return array<class-string<Node>>
     */
    public function getNodeTypes(): array
    {
        // select node type
        return [ClassConstFetch::class];
    }
...

今回はClassConstFetchのみですが、複数指定する事も可能です。ここで指定したnodeがfetchされ次に解説するrefactor()の引数に渡されます。

refactor()

fetchしたnodeに変更を加えてコードをリファクタします。まず、引数で渡された$nodeがどういうものなのか見てみましょう。refactor()内にeval(\Psy\sh())を挿入してrectorを実行してみると以下の様に出力されました。（rectorの実行方法については後で解説します。）

From utils/rector/src/Rector/ReplaceConstantToEnumValueRector.php:48:
    46:     public function refactor(Node $node): ?Node
    47:     {
  > 48:         eval(\Psy\sh());
    49: 
    50:         $constName = $this->getName($node->name);
> $node
= PhpParser\Node\Expr\ClassConstFetch {#24984
    +class: PhpParser\Node\Name {#24985
      +parts: [
        "self",
      ],
    },
    +name: PhpParser\Node\Identifier {#24986
      +name: "ORDER_STATUS_CANCELED",
    },
  }

getNodeTypes()で指定した通り、ClassConstFetchクラスのインスタンスが代入されていますね。ここでfetchしたnodeはself::ORDER_STATUS_CANCELEDに当たる部分なので、クラス名部分がself、変数名部分がORDER_STATUS_CANCELEDとしてそれぞれclass, nameプロパティから辿れます。それによって、更にリファクタしたい対象を絞り込む事ができます、以下の様に。

utils/rector/src/Rector/ReplaceConstantToEnumValueRector.php

...
    /**
     * @param ClassConstFetch $node
     */
    public function refactor(Node $node): ?Node
    {
        $constName = $this->getName($node->name);

        // ORDER_STATUS_* の場合のみリファクタ
        if (Str::startsWith($constName, 'ORDER_STATUS_')) {
            // リファクタ処理
        }

        return $node;
    }
...

$this->getName($node->name)の部分で変数名部分を取得し、それがORDER_STATUS_から始まるならリファクタ処理を実行、としました。

次にリファクタ処理を実装します。リファクタ処理はOrderStatus::XXX->valueを表現するnodeを新たに作成して返却します。nodeの作成は$this->nodeFactoryのメソッドをcallして行います。（実行可能なメソッドはRector\PhpParser\Node\NodeFactoryをご覧ください。）以下の様に実装しました。

utils/rector/src/Rector/ReplaceConstantToEnumValueRector.php

...
    /**
     * @param ClassConstFetch $node
     */
    public function refactor(Node $node): ?Node
    {
        $constName = $this->getName($node->name);

        // ORDER_STATUS_*
        if (Str::startsWith($constName, 'ORDER_STATUS_')) {
            // ORDER_STATUS_以降を取得
            $case = Str::after($constName, 'ORDER_STATUS_');

            // OrderStatus::XXX のnodeを作成
            $constFetch = $this->nodeFactory->createClassConstFetch('App\\Enums\\OrderStatus', $case);

            // OrderStatus::XXX にvalueプロパティを参照させる（OrderStatus::XXX->value）
            return $this->nodeFactory->createPropertyFetch($constFetch, 'value');
        }

        return $node;
    }
...

これでカスタムルールの作成が完了です。

リファクタ実行

最後にrector.phpを設定してリファクタを実行してみましょう。rector.phpは以下の様に設定しました。

rector.php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Utils\Rector\Rector\ReplaceConstantToEnumValueRector;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/app/Models/Order.php',
    ])
    ->withRules([
        ReplaceConstantToEnumValueRector::class,
    ])
    ->withImportNames();

withPaths()にてリファクタを適用するファイルを指定、withRules()にて適用するルールを指定しています。また、OrderStatusが完全修飾名となっているのでwithImportNames()を追加して名前空間をインポート（use App\Enums\OrderStatus;を追加）するようにしています。これでrectorを実行してみます。実際にリファクタを適用する前にコードがどの様に変化するのか、dry runで確認してみましょう。

$ vendor/bin/rector --dry-run        
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
1 file with changes
===================

1) app/Models/Order.php:1

    ---------- begin diff ----------
@@ @@

 namespace App\Models;

+use App\Enums\OrderStatus;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Factories\HasFactory;

@@ @@
     // キャンセルされた？
     public function isCanceled()
     {
-        return $this->status === self::ORDER_STATUS_CANCELED;
+        return $this->status === OrderStatus::CANCELED->value;
     }

     // 売上として計上された注文
     public function scopeAsRevenue($query)
     {
-        return $query->whereIn('status', [self::ORDER_STATUS_ORDERED, self::ORDER_STATUS_SHIPPED]);
+        return $query->whereIn('status', [OrderStatus::ORDERED->value, OrderStatus::SHIPPED->value]);
     }

 }
    ----------- end diff -----------

Applied rules:
 * ReplaceConstantToEnumValueRector
                                                                                                                        
 [OK] 1 file would have been changed (dry-run) by Rector

差分を見ての通り、self::ORDER_STATUS_XXXだった箇所がOrderStatus::XXX->valueに変換されていますね。問題なさそうなのでdry runオプションを外して実行します。

$ vendor/bin/rector

以下が変換後のOrder.phpです。

app/Models/Order.php

namespace App\Models;

use App\Enums\OrderStatus;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Factories\HasFactory;

class Order extends Model
{
    use HasFactory;

    // order status constants
    const ORDER_STATUS_ORDERED = 0;
    const ORDER_STATUS_SHIPPED = 1;
    const ORDER_STATUS_CANCELED = 2;

    protected $table = 'order';

    protected $primaryKey = 'order_id';

    protected $guarded = ['order_id', 'created_at', 'updated_at'];

    // キャンセルされた？
    public function isCanceled()
    {
        return $this->status === OrderStatus::CANCELED->value;
    }

    // 売上として計上された注文
    public function scopeAsRevenue($query)
    {
        return $query->whereIn('status', [OrderStatus::ORDERED->value, OrderStatus::SHIPPED->value]);
    }

}

変換後のファイルを見ると定数の定義部分が残っていますね。こちらもまた別のカスタムルールを作成して削除できます。こうして１つずつ作業を棚卸ししてRectorのカスタムルールを作成していく事で膨大なリファクタ作業を大幅に短縮させる事が可能です。是非試してみて下さい。

参照

Rectorでリファクタリングを自動化　その１ Rectorでリファクタリングを自動化　その２

Rectorでリファクタリングを自動化　その２

Fri, 12 May 2023 00:50:55 +0900

前回の記事ではRectorを使ってプロジェクト内の古い記法を書き換える手順を紹介しました。書き換えたい記法が１つの場合は前回の解説で十分だと思いますが、例えば、PHPのアップグレードに合わせて新たに導入された記法をまとめて適用したい、という場合は Set Lists を使うのがオススメです。今回はそちらの手順を紹介します。

Set Lists

セットリストはいくつかのルールをトピック別にグループ化したものです。例えば設定ファイルを以下の様に書き換えると、PHP8.0で導入された記法をまとめて適用することができます。

rector.php

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\SetList;

return static function (RectorConfig $rectorConfig): void {

    // app 配下のみを対象にする
    $rectorConfig->paths([
        __DIR__ . '/app',
    ]);

    // PHP8.0で導入された変更を適用する
    $rectorConfig->sets([SetList::PHP_80]);
};

指定可能なセットリストは以下です。

https://github.com/rectorphp/rector/blob/main/packages/Set/ValueObject/SetList.php

PHPバージョン別に導入された記法であったり、コーディングスタイルであったり、デッドコードであったり、色々ありますね。

各セットリストで適用される変更はRules OverviewのCategoriesから確認できます。

Level Sets

PHPのバージョンアップ用にLevel Set Listというセットリストも用意されています。これは、指定したバージョン以前のruleもまとめて適用したい場合に使えます。例えば、前項のサンプルコードの様に、

$rectorConfig->sets([SetList::PHP_80]);

とした場合はPHP8.0のruleのみ適用されますが、PHP7.2, 7.3, 7.4 のruleもまとめて適用したい場合は

$rectorConfig->sets([LevelSetList::UP_TO_PHP_80]);

とすれば変更に含まれます。

一部のruleを無視する

ruleをまとめて適用できるセットリストは便利ですが、プロジェクトによってはセットリストに含まれる１部のruleを除外したいケースがあるかもしれません。その場合は以下の様にskip()を使って除外したいruleを指定します。

例えば、以下のように変更するとswitch文をmatch文に変更するルールが無視されます。

rector.php

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;
use Rector\Php80\Rector\Switch_\ChangeSwitchToMatchRector;

return static function (RectorConfig $rectorConfig): void {

    // app 配下のみを対象にする
    $rectorConfig->paths([
        __DIR__ . '/app',
    ]);

    // PHP8.0で導入された変更を適用する
    $rectorConfig->sets([LevelSetList::UP_TO_PHP_80]);

    // switch -> match への変更を無視する
    $rectorConfig->skip([
        ChangeSwitchToMatchRector::class,
    ]);
};

まとめ

いかがでしたでしょうか。

普段PHPのバージョンを上げる際は廃止される記法の書き換えはmustで行いますが、新しい記法の導入には慎重になりがちです。

その理由の１つに、書き換えた結果どれ位コードが良くなるか分からないから、というのがあります。

しかし、Rectorを活用することで取り敢えず書き換えてみる、その上で取り入れるかどうか検討してみる、といった事もできそうです。

参照

Rectorでリファクタリングを自動化　その１ Rectorでリファクタリングを自動化　その３

Rectorでリファクタリングを自動化　その１

Mon, 01 May 2023 01:30:18 +0900

前回紹介したmatch式や Constructor Property Promotion のように新しい記法が導入されることでボイラープレートが駆逐されコードがより簡潔に読みやすくなります。しかし、長年運用されているプロジェクトなどでは書き換え必要な箇所が多く、導入するのに及び腰になってしまいがちです。Rectorを使うことでそんな億劫な作業が一瞬で完了するかもしれませんよ。

Rectorとは？

About Rectorより

「Rector」とは、どんなPHPプロジェクトでも実行可能なPHPツールであり、瞬時にアップグレードや自動リファクタリングを実行できます。

という事で、まさにPHP8から導入されたsyntaxで書き換えたい、という私の要求にマッチしています。それらを自動で行なってくれるなら大助かりです。

現時点（2023/04/22）で ver 0.15.23 が最新で実行にはPHP7.2以上が必要となっています。

どんなツールか早速使って体感してみましょう。

インストール

新しく作成したLaravelのprojectにてインストールしました。

composer require rector/rector --dev

すると vendor/bin/rector が追加されます。

vendor/bin/rector --version
>> Rector 0.15.25

設定ファイルを追加

次に設定ファイルを（rector.php）プロジェクトに追加します。

vendor/bin/rector init

// rector.php を作成するか問われるので yes とタイプ
No "rector.php" config found. Should we generate it for you? [yes]:
> yes

[OK] The config is added now. Re-run command to make Rector do the work!

プロジェクトのルートディレクトリに rector.php が作成されました。デフォルトでは以下の状態です。

rector.php

<?php

declare(strict_types=1);

use Rector\CodeQuality\Rector\Class_\InlineConstructorDefaultToPropertyRector;
use Rector\Config\RectorConfig;
use Rector\Set\ValueObject\LevelSetList;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        __DIR__ . '/app',
        __DIR__ . '/bootstrap',
        __DIR__ . '/config',
        __DIR__ . '/lang',
        __DIR__ . '/public',
        __DIR__ . '/resources',
        __DIR__ . '/routes',
        __DIR__ . '/tests',
    ]);

    // register a single rule
    $rectorConfig->rule(InlineConstructorDefaultToPropertyRector::class);

    // define sets of rules
    //    $rectorConfig->sets([
    //        LevelSetList::UP_TO_PHP_80
    //    ]);
};

リファクタリングしたいパスは

$rectorConfig->paths([...]);

にて指定できます。

また、適用したい変更をruleとして指定します。

$rectorConfig->rule(InlineConstructorDefaultToPropertyRector::class);

// 複数のruleをまとめて指定するならrules
$rectorConfig->rules([
    InlineConstructorDefaultToPropertyRector::class,
    InlineIfToExplicitIfRector::class
]);

Rectorで扱うリファクタリングは主に記法の統一なので、「こういう時はこう書きましょう」というルールを定めるイメージですね。

Rules Overview にて指定可能なルールがまとめられていますので、ご確認を。

実践

前回紹介した Constructor Property Promotion についてリファクタリング可能か試してみましょう。

まず、以前の記事で使用した例と同じ Person.php を app/Models/ 配下に作成します。

app/Models/Person.php

<?php

namespace App\Models;

class Person
{
    public string $name;
    public int $age;
    public string $sex;
 
    public function __construct(string $name, int $age, string $sex)
    {
        $this->name = $name;
        $this->age = $age;
        $this->sex = $sex;
    }
}

次に、rector.php を以下のように書き換え設定します。

rector.php

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Php80\Rector\Class_\ClassPropertyAssignToConstructorPromotionRector;

return static function (RectorConfig $rectorConfig): void {

    // app 配下のみを対象にする
    $rectorConfig->paths([
        __DIR__ . '/app',
    ]);

    // Constructor Property Promotion を適用するruleを追加
    $rectorConfig->rule(ClassPropertyAssignToConstructorPromotionRector::class);
};

Constructor Property Promotion に書き換えるruleはこちらにありました。

準備が整ったので書き換えてみましょう。まずは–dry-runを付けて実行します。

vendor/bin/rector process --dry-run

–dry-runではコード自体は変更されません。変更前後の差分が表示されるので、それを見て意図通りの変更が適用されるか事前確認します。

1 file with changes
===================

1) app/Models/Person.php:3

    ---------- begin diff ----------
@@ @@

 class Person
 {
-    public string $name;
-    public int $age;
-    public string $sex;
- 
-    public function __construct(string $name, int $age, string $sex)
+    public function __construct(public string $name, public int $age, public string $sex)
     {
-        $this->name = $name;
-        $this->age = $age;
-        $this->sex = $sex;
     }
 }
    ----------- end diff -----------

Applied rules:
 * ClassPropertyAssignToConstructorPromotionRector (https://wiki.php.net/rfc/constructor_promotion https://github.com/php/php-src/pull/5291)



 [OK] 1 file would have changed (dry-run) by Rector

意図通りの変更が施されていますね。問題無かったので今度は–dry-runオプションを省いて実行します。

vendor/bin/rector process

Person.php がリファクタリングされ以下となりました。

app/Models/Person.php

<?php

namespace App\Models;

class Person
{
    public function __construct(public string $name, public int $age, public string $sex)
    {
    }
}

まとめ

長くなってしまったのでRector導入編、ということで一旦ここで切ります。今回の記事では掘り下げられなかったSet Listsについては次回以降の記事で紹介できればと思います。

今回は解説用なので１ファイルのみのリファクタリングとなりましたが、大きいプロジェクトであれば数十数百のファイルにコマンド一発で変更が適用されるので記法を置換する際にはとても便利なツールだと思います。

また、今回は古い記法を置換する目的で触ってみましたが、例えばチームで開発している際に以前に紹介されたpintなどと同様にコードスタイルを統一する目的でも活用できるのでは、と思います。

参照

Rectorでリファクタリングを自動化　その２ Rectorでリファクタリングを自動化　その３

Rector on ララジャパン

Rectorでリファクタリングを自動化 その３

Rectorのインストール(おさらい）

自作ルールでリファクタリングを自動化

定数をEnumに変換する

カスタムルール作成

カスタムルールを定義

getRuleDefinition()

getNodeTypes()

refactor()

リファクタ実行

参照

Rectorでリファクタリングを自動化 その２

Set Lists

Level Sets

一部のruleを無視する

まとめ

参照

Rectorでリファクタリングを自動化 その１

Rectorとは？

インストール

設定ファイルを追加

実践

まとめ

参照

Rectorでリファクタリングを自動化　その３

Rectorでリファクタリングを自動化　その２

Rectorでリファクタリングを自動化　その１