はじめに

こんにちは、株式会社divxでエンジニアをしている今度です。
現在、PHPを使用したWebアプリケーションの保守・運用プロジェクトに携わっています。
このプロジェクトでPHP Stan（PHP Static Analysis Tool） を導入しました。
今回は、PHPの静的解析ツールであるPHP Stanについて簡単に説明していきたいと思います。
静的解析ツールを導入していないプロジェクトに携わっているエンジニアの方やPHP Stanに興味があるエンジニアの方へ参考になれば幸いです。

静的解析とは

静的解析とは、ソフトウェアのソースコードを実行せずに解析する手法です。
以下に静的解析の目的を挙げます。

• バグの早期発見
  • コーディングの段階で潜在的なバグを発見することで、後のテストや運用段階での問題発生を減少させる
• コード品質の向上
  • コードが一貫していて、読みやすく、保守しやすいかどうかを確認する
• セキュリティの強化
  • 潜在的なセキュリティ脆弱性を検出する
• 標準遵守
  • コードが指定されたコーディング標準やベストプラクティスに従っているかチェックする

静的解析には様々なツールが存在しています。
その中でも今回はPHP Stanについて掘り下げていきます。

PHP Stanとは

まずPHP Stanとは、PHPコードの静的解析を行うツールになります。
PHPコードを実行せずにコードベース全体を解析し、型や構造に関する問題を指摘します。
これによりアプリケーションを実行した時にはじめて気づくような問題を未然に察知することができます。

• PHP Stan 公式：https://phpstan.org/user-guide/getting-started
• PHP Stan GitHub：https://github.com/phpstan/phpstan

PHP Stan実践

PHP Stanのインストール

PHP Stanのダウンロードには PHP 7.2以降 が必要となりますので、ご注意ください。
PHP Stanは Composer パッケージとして公開されているので、composerコマンドでインストールすることができます。
下記のようにコマンドを実行すれば PHP Stanがインストールされ、phpstanコマンドが利用できるようになります。

composer require --dev phpstan/phpstan

ちなみに、PHP Stanには公式のDockerファイルも用意されています。
Composerを利用していないプロジェクトやプロジェクトのcomposer.jsonにPHP Stanを導入したくない場合などに利用できます。
DockerでPHP Stanを使用する場合は、こちらを参照してください。

設定方法

プロジェクトのルートディレクトリでphpstan.neon というファイル名で設定ファイルを作成します。
設定ファイルは下記のようになります。

parameters:
    paths:
        - app/src
    level: 0

• paths： 解析対象のコードディレクトリを指定します。ここではapp/srcを指定しています。
• level：適用するルールレベルを指定します。ここでは最も緩い「0」を指定しています。

PHP Stan実行

PHP Stanを実行するには、phpstan コマンドを利用します。
またanalyse サブコマンドで、適切なディレクトリを指定すると設定ファイルの内容に従って静的解析を行い、エラーを出力します。
例えば、app/srcディレクトリを解析したい場合は、以下のコマンドを実行します。

vendor/bin/phpstan analyse app/src

このコマンドは、app/src内のPHPファイルを解析し、問題があれば表示します。

エラーが検出された場合は、下記のような出力になります。
エラーが検出されたファイル名、行番号、エラー内容を示すメッセージが出力されます。

ここでは、src/Example.phpの23行目で、未定義のメソッドを呼び出しているため警告が表示されています。
このようにPHPコードを実行せずにコードの問題点を検出することができます。

ルールレベル

PHP Stanには現在10レベル(0が最も緩く、9が最も厳密)用意されており、必要に応じてレベルを選択することができます。
この機能により、PHP Stanチェックを段階的に導入できるようになります。
低いルールレベルで使い始めて、必要に応じてレベルを上げることができます。

例えばレベル5を実行すると、レベル0～4のすべてのチェックも実行される仕様です。

エラーを無視する方法

あるレベルで検出されたエラーを今時点では修正が難しいなどのさまざまな理由によりPHP Stan
によって検出されたいくつかのエラーを無視したい場合が出てくると思います。
そのような場合は、baselineファイルを作成して、エラーを無視するようにします。
baselineファイルの生成には、php stanコマンドの--generate-baselineオプションを利用します。
下記のように実行すると、phpstan-baseline.neonというファイルに無視するエラーが記録されていきます。

./vendor/bin/phpstan analyse --generate-baseline
Note: Using configuration file /path/to/phpstan.neon.
 2/2 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 [OK] Baseline generated with 1 errors.

生成されたphpstan-baseline.neonは下記のようになります。
ignoreErrorsキーに無視するエラーメッセージ、ファイル名、回数が記述されます。

parameters:
    ignoreErrors:
        -
            message: "#^Call to an undefined static method Foo\\:\\:sub\\(\\)\\.$#"
            count: 1
            path: index.php

設定方法で作成したphpstan.neonファイルに、このファイルを読み込むように指定します。
下記のように追加することでphpstan-baseline.neonファイルを読み込み、エラーを無視できる
ようになります。

# 追加
includes:
    - phpstan-baseline.neon
parameters:
    paths:
        - app/src
    level: 0

※エラーを無視しても、最終的にエラーを解決する必要があります。

実際に使ってみた感触

• 導入のしやすさ
  • 手順も少なく、すぐに導入することができる
• 柔軟に対応可能
  • 状況に応じて、ルールレベルや実行範囲を変更することができる
• 早期発見
  • コードの実行前に静的解析を行うため、バグやエラーを早期に発見できる
• コード品質向上
  • コードの可読性や保守性を向上させることができる

まとめ

今回は、静的解析ツールであるPHP Stanについて書かせていただきました。
PHP Stanは導入もしやすく、エラーやバグの早期発見ができるなど多くのメリットがあります。
またルールレベルを簡単に変更することができるため、柔軟にかつ段階的に導入することができます。
実際にプロジェクトではレベル0から始めましたが、このレベルでも多くのエラーやバグを発見し
てくれたので十分に導入する効果はあると感じました。
ぜひ、導入されてみてはいかがでしょうか！

お悩みご相談ください