PHPStanによるコード品質の向上: カスタムルールの追加

現代のPHP開発において、コードの品質を保つことは非常に重要です。
特に大規模なプロジェクトや長期間にわたる開発では、
効率的なコード管理と品質維持がプロジェクト成功の鍵となります。

この記事では、PHPの静的解析ツールであるPHPStanを活用し、
プロジェクトの品質を向上させる方法について解説します。

具体的には、PHPStanでのカスタムルールの追加方法に焦点を当てます。
これらの技術を駆使することで、PHP開発の効率と品質を同時に高めることができます。

phpstan.neonを用いたPHPStanによる静的解析

カスタムルールを追加する前に、まずはphpstan.neonを用いてPHPStanを動かしましょう。
phpstan.neonは、PHPStanの設定ファイルになります。

では、段階を踏んで説明していきます。

上記のようなプロジェクトがあるとします。
コードの中身は、以下。

test.php

<?php
    print(1);
?>

このプロジェクトを対象に静的解析をPHPStanで実施します。
インストール方法は、以下の記事で説明しています。

情報は古くなっていますが、やることは同じです。
まずは、Composerを用意します。

そして、プロジェクトルートで次のコマンドを実行。

composer require --dev phpstan/phpstan

実行すると、次のように処理が行われます。

>composer require --dev phpstan/phpstan
./composer.json has been created
Running composer update phpstan/phpstan
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking phpstan/phpstan (1.10.60)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Installing phpstan/phpstan (1.10.60): Extracting archive
Generating autoload files
1 package you are using is looking for funding.
Use the `composer fund` command to find out more!
No security vulnerability advisories found.
Using version ^1.10 for phpstan/phpstan

その結果、以下のような構成となります。

とりあえず、PHPStanがインストールされたことを確認しましょう。

> ./vendor/bin/phpstan analyse --version
PHPStan - PHP Static Analysis Tool 1.10.60

確認できたら、「phpstan.neon」をプロジェクトルートに作成します。

現時点では、以下のように記述しておきます。

phpstan.neon

parameters:
    paths:
        - php
    level: 0

これで静的解析が開始可能となります。
以下のコマンドで実行できます。

./vendor/bin/phpstan analyse

実行した結果は、以下のようになります。

対象は「php」ディレクトリ以下のファイル（test.php）です。
エラーがない状況と言えます。

PHPStanにおけるカスタムルールの追加

カスタムルールの追加には、以下の作業が必要となります。

composer.jsonの修正
カスタムルールの作成
phpstan.neonの修正

これらを以下で説明します。

composer.jsonの修正

composer.json

{
    "require-dev": {
        "phpstan/phpstan": "^1.10"
    }
}

このファイルを以下のように修正します。

{
    "require-dev": {
        "phpstan/phpstan": "^1.10"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

上記の処理がよくわからない場合は、「PSR-4 Autoloader（オートローダー）」で検索してください。
上記修正に合わせて、「src」ディレクトリを作成します。

あと、composer.jsonを修正したので、次のコマンドで反映しておきます。

composer dump-autoload

次のように表示されたら、OK。

> composer dump-autoload                                                                
Generating autoload files
Generated autoload files

カスタムルールの作成

カスタムルールは、PHPでコーディングできます。
ここでは、以下のようなクラスを作成します。

ForbiddenPrintRule.php

<?php

namespace App\PHPStan\Rules;

use PhpParser\Node;
use PhpParser\Node\Expr\Print_;
use PHPStan\Analyser\Scope;
use PHPStan\Rules\Rule;

class ForbiddenPrintRule implements Rule
{
    public function getNodeType(): string
    {
        return Print_::class;
    }

    public function processNode(Node $node, Scope $scope): array
    {
        // `print`命令が使われている場合、エラーメッセージを返す
        return ['Using print function is forbidden.'];
    }
}

カスタムルールの作成には、AST（Abstract Syntax Tree）の知識が必要となります。

Abstract Syntax Tree

しかし、そんなに恐れる必要はありません。
ChatGPTやClaudeを利用すれば、簡単に作成できます。

作成したファイルは、以下のように設置します。

phpstan.neonの修正

phpstan.neonに追加したカスタムルールを追加しましょう。

parameters:
    paths:
        - php
    level: 0

services:
    -
        class: App\PHPStan\Rules\ForbiddenPrintRule
        tags:
            - phpstan.rules.rule

修正できたら、再度PHPStanによる静的解析を行います。