🍖

Rector で始める自動リファクタリング入門

2020/11/01に公開

3件

PHP

rector

tech

はじめに

みなさん, リファクタリングはしていますでしょうか。
リファクタリングと一口に言っても様々な性格のものが存在しますが, その中でもある一定のルールに基づく機械的な作業が要求されるものがあるかと思います。

例えば,

全ての関数 A を関数 B に変えたい
クラス A を継承している全てのクラスの親クラスをクラス B に変えたい
コンストラクタ内でクラスをインスタンス化している処理を DI パターンに変えたい

などなど……。

小規模なものであれば手作業でおこなっても問題のないことが多いですが, 大規模になるとうっかりミスが発生しがちだったり単純作業ゆえの精神的な苦痛が伴うこともあったりなど, あまり好ましくありません。

本記事で紹介する Rector はそういった機械的な作業からエンジニアを開放するとてもすごいツールです。

是非本記事で Rector の基本的な使い方を覚え, 日々の業務を楽にしてみてください。

サンプルプロジェクトの構築

本記事では予め用意されたサンプルコードに対して Rector を実際に実行することで理解を深めていきたいと思います。

推奨環境

git clone

作業ディレクトリから以下のコマンドを実行しサンプルプロジェクトをローカル環境に構築します。

$ git clone git@github.com:YAhiru/rector-tutorial.git
$ cd rector-tutorial

サンプルプロジェクトの確認

サンプルプロジェクトは以下の構成になっています。

.
├── rector    # Rector 用のディレクトリ
│   ├── src   # 記事の終盤で作成する独自ルール用のディレクトリ
│   └── tests # 独自ルールのテストディレクトリ
├── src       # サンプルのアプリケーションコードディレクトリ
└── tests     # サンプルのアプリケーションコードのテストディレクトリ

理由は後述しますが Rector 用のディレクトリとサンプルのアプリケーションコードを分けています。

ここでいうアプリケーションコードとは Web アプリケーションであればコントローラーやエンティティなどに当たるもので, リファクタリングの対象となるコードです。
今回は src ディレクトリに単純なクラスを 1 つだけ用意しています。

rector ディレクトリは本記事の後半で実装する独自ルールのためのディレクトリとなっていますので, 最低限の設定のみでほぼ空の状態となっています。

インストール

Rector は composer req --dev rector/rector を実行して利用する他に phar や docker などの形式が用意されています。
Rector の依存関係を確認するとわかる通り依存するライブラリが非常に多いため, ルールを自作したいなどのニーズがない場合は phar あるいは docker 形式での利用をおすすめします。

今回は最終的にルールを自作したいため rector/rector を composer 経由でダウンロードするわけですが, 前述の通り依存関係が多いため既存のプロダクトにインストールすることができないといった問題の発生が予想されます。
そういった場合に有効なのが Rector 用のサブディレクトリを作成しその中で Rector 関連のコードを完結させることです。^[1]
今回のサンプルプロジェクトでもそのアプローチを採用しています。

また、その他の構成についてはこちらの記事も非常に参考になります。

では, 以下のコマンドで Rector のインストールをします。

$ cd rector
$ composer req rector/rector

ルールを適用してみる

それでは Rector を試していきたいと思います。
今回自動リファクタリングをしてみるファイルは src/User.php です。

src/User.php

final class User
{
    /** @var string */
    private $screenName;
    /** @var int */
    private $age;

    public function __construct(string $screenName, int $age)
    {
        $this->screenName = $screenName;
        $this->age = $age;
    }

    // ...
}

User クラスのプロパティである $screenName や $age を見てみると Typed Property が適用されていないことがわかります。
Typed Property が適用されていない場合 PHP Doc に記述された型以外が代入された場合でもエラーが発生せず, 思わぬバグを引き起こす可能性を秘めています。
あなたの所属するチーム内でこのことが問題視されたという設定で, Rector を使ってこのクラスを自動リファクタリングしてみましょう。

Rector を実行する

Rector の実行は簡単で vendor/bin/rector process {{ディレクトリ}} --set {{ルールセット}} のように, process コマンドに対してターゲットとなるディレクトリや適用したい ルールセット, ルール を渡せば良いだけです。

名前	説明
ルール	リファクタリングの内容が定義された PHP のクラス
ルールセット	関心ごとが近い複数のルールがまとめられたもの

今回は Typed Property だけを適用してくれればよいので, php74 というルールセットの中にある Rector\Php74\Rector\Property\TypedPropertyRector というルールのみを適用したいと思います。

rector ディレクトリ内で以下のコマンドを実行してみましょう。

rector/

$ vendor/bin/rector process ../src \
    --set php74 \
    --only 'Rector\Php74\Rector\Property\TypedPropertyRector'

修正されたファイルを確認する

コマンドを実行するとそれっぽさのある出力がなされたかと思いますが, 実際の User クラスを確認してみると以下のように $screenName と $age に Typed Property が適用されていることがわかります。

src/User.php

final class User
{
    private string $screenName;
    private int $age;

    public function __construct(string $screenName, int $age)
    {
        $this->screenName = $screenName;
        $this->age = $age;
    }

    // ...
}

どうですか！！！！！！！！すごくないですか！？！？！？！？！？！？！？！？（唐突な興奮）

Rector を使ってリファクタリングを自動化することで修正規模によっては工数を大幅に削減することが出来るため, あなたの上司もニッコリです。

ルールの自作

リファクタリングの要件はプロダクトによって様々なので Rector が用意してくれているルールだけでは要件を満たせないことがあります。
そういった場合に有効なのがルールの自作です。

独自のルールを作ることが出来ればプロダクト固有の要件であってもリファクタリングを自動化することができます。

今回はあなたの所属するチーム内で「PHPUnit のテストメソッドは, メソッド名に test という prefix を付ける形式ではなく @test アノテーションを使う形式にしたい」という要望が出たという設定で進めていきましょう。^[2]

独自ルールのテストを書く

早速独自のルールを作っていきたいのですが, まずはどのようなコードをどのようにリファクタリングしたいのかということを明確にする必要があります。
Rector はテスト基盤も整っていますので, テストを書くことでルールのイメージを固めていきましょう。

ルールのテストでは必要なものが 2 つあります。

テストクラス
Fixture

テストクラス

ここでいうテストクラスとは PHPUnit\Framework\TestCase を継承した任意のクラスのことです。
Rector には PHPUnit\Framework\TestCase を拡張した Rector\Core\Testing\PHPUnit\AbstractRectorTestCase ^[3] が用意されており, これによってルールのテストがとても簡単になるため今回はこれを利用します。

rector ディレクトリ内で以下のコマンドを実行してテストクラス用のファイルを作成します。

rector/

$ mkdir -p tests/AddTestAnnotationRector
$ touch tests/AddTestAnnotationRector/AddTestAnnotationRectorTest.php

ファイルが作成されたら, ファイルに以下の内容を書き込みます。

rector/tests/AddTestAnnotationRector/AddTestAnnotationRectorTest.php

<?php
declare(strict_types=1);
namespace Yahiru\RectorTutorialRector\AddTestAnnotationRector;

use Iterator;
use Rector\Core\Testing\PHPUnit\AbstractRectorTestCase;
use Symplify\SmartFileSystem\SmartFileInfo;
use Yahiru\RectorTutorialRector\AddTestAnnotationRector;

final class AddTestAnnotationRectorTest extends AbstractRectorTestCase
{
    /**
     * @dataProvider provideData()
     */
    public function test(SmartFileInfo $fileInfo) : void
    {
        $this->doTestFileInfo($fileInfo);
    }

    /**
     * @return Iterator<SmartFileInfo>
     */
    public function provideData() : Iterator
    {
        return $this->yieldFilesFromDirectory(__DIR__ . '/Fixture');
    }

    protected function getRectorClass() : string
    {
        return AddTestAnnotationRector::class;
    }
}

getRectorClass() はテスト対象となるルールのクラス名を返却します。

rector/tests/AddTestAnnotationRector/AddTestAnnotationRectorTest.php

    protected function getRectorClass(): string
    {
        return AddTestAnnotationRector::class;
    }

ここで返却したルールを Rector\Core\Testing\PHPUnit\AbstractRectorTestCase 内でよしなに扱ってくれます。
AddTestAnnotationRector クラスはまだ存在していませんが, テストを実装した後に作成する予定です。

provideData() はこの後作成する予定の Fixture ファイルを読み込み, test() は読み込まれた Fixture を利用してテストを実行します。

rector/tests/AddTestAnnotationRector/AddTestAnnotationRectorTest.php

    /**
     * @dataProvider provideData()
     */
    public function test(SmartFileInfo $fileInfo): void
    {
        $this->doTestFileInfo($fileInfo);
    }

    /**
     * @return Iterator<SmartFileInfo>
     */
    public function provideData(): Iterator
    {
        return $this->yieldFilesFromDirectory(__DIR__ . '/Fixture');
    }

Fixture

Fixture とは, 以下のフォーマットで リファクタリング前のコード と リファクタリング後のコード が記述されたファイルのことです。

<?php
リファクタリング前のコード
?>
-----
<?php
リファクタリング後のコード
?>

実際の Fixture を見た方が理解が早いので, 早速 Fixture を作ってみましょう。
rector ディレクトリ内で以下のコマンドを実行してファイルを作成します。

rector/

$ mkdir -p tests/AddTestAnnotationRector/Fixture
$ touch tests/AddTestAnnotationRector/Fixture/fixture.php.inc

今回は test という prefix がついているテストメソッドを @test アノテーション形式に変換するというのが要件ですので, 作成したファイルに以下の内容を書き込みます。

rector/tests/AddTestAnnotationRector/Fixture/fixture.php.inc

<?php
namespace Yahiru\RectorTutorialRector\AddTestAnnotationRector\Fixture;

class SomeTest extends \PHPUnit\Framework\TestCase
{
    public function testSome() : void
    {
        // do test
    }
}

?>
-----
<?php
namespace Yahiru\RectorTutorialRector\AddTestAnnotationRector\Fixture;

class SomeTest extends \PHPUnit\Framework\TestCase
{
    /**
     * @test
     */
    public function some() : void
    {
        // do test
    }
}

?>

書き込んだ内容が前述のフォーマット通りになっていることを確認してください。
使用しているエディターによっては上記のコードをコピペした際にリファクタリング前と後の区切りを表す ----- の直前にスペースが入り込むことがあるので注意してください。

作成した Fixture の差分は以下の通りで, テストメソッドが @test アノテーション形式に変わっています。

+   /**
+    * @test
+    */
+   public function some() : void
-   public function testSome() : void
    {
        // do test
    }

注意点

Fixture を作成する上での重要な注意点ですが, Rector はリファクタリング対象のコードを動的に読み込みます。

つまり今作成した Fixture に定義されているクラスも読み込まれるということなので, Fixture にうっかり namespace を書き忘れてしまうと, 他のテストの Fixture や既存クラスとクラス名が衝突する可能性が増します。

なので絶対に Fixture には namespace を書くようにしましょう。

Fixture を複数用意する

テストの準備自体はこれで完了ですが, テスト項目が足りていないのでもう少し Fixture を増やしたいと思います。

今回の独自ルールにおいて, メソッドがリファクタリング対象であると判断する基準は以下とします。

クラスが PHPUnit\Framework\TestCase を継承していること
メソッド名が test で始まっていること
メソッドの可視性が public であること

正常系は先ほどの Fixture でテストできているので, 次は上記の条件以外ではリファクタリングされないことを保証する Fixture を追加します。

rector ディレクトリ内で以下のコマンドを実行してファイルを作成してください。

rector/

$ touch tests/AddTestAnnotationRector/Fixture/{no-test-prefix.php.inc,not-public-method.php.inc,not-test-class.php.inc}

コードの変更がない場合の Fixture はリファクタリング後のコードを省くことが可能ですので, それぞれのファイルに以下の内容を書き込みんでください。

rector/tests/AddTestAnnotationRector/Fixture/no-test-prefix.php.inc

<?php
namespace Yahiru\RectorTutorialRector\AddTestAnnotationRector\Fixture;

class NotTestPrefix extends \PHPUnit\Framework\TestCase
{
    public function noPrefix() : void
    {
    }
}

rector/tests/AddTestAnnotationRector/Fixture/not-public-method.php.inc

<?php
namespace Yahiru\RectorTutorialRector\AddTestAnnotationRector\Fixture;

class NotPublicMethodTest extends \PHPUnit\Framework\TestCase
{
    protected function testProtected() : void
    {
    }

    private function testPrivate() : void
    {
    }
}

rector/tests/AddTestAnnotationRector/Fixture/not-test-class.php.inc

<?php
namespace Yahiru\RectorTutorialRector\AddTestAnnotationRector\Fixture;

class NotTest
{
    public function testSome() : void
    {
    }
}

Fixture の準備はこれで完了です。
蛇足ですが, テストしたい内容を明確にするために Fixture は適切な粒度で分けることを意識すると良いでしょう。

独自ルールを作る

次は独自ルールを作成します。
ルールは基本的に Rector\Core\Rector\AbstractRector を継承して作成します。

rector ディレクトリ内で以下のコマンドを実行してファイルを作成してください。

rector/

$ touch src/AddTestAnnotationRector.php

作成したファイルに以下の内容を書き込んでください。