PHPStan の使い方

PHPStan は Composer を使ってインストールします。下記のコマンドを実行するだけです。 基本的には開発環境で使うツールだと思うので、--dev オプションを付けておきましょう。 Composer の使い方がわからないという方は、まずは「Composer の使い方（その１：概要）」を参考にしてください。

php composer.phar require --dev "phpstan/phpstan"

.\vendor\bin\phpstan -h

1つのファイルを解析する場合は、解析したいファイル名を指定します。 解析したいファイル名はスペース区切りで複数指定できます。

.\vendor\bin\phpstan analyse .\src\hoge.php

.\vendor\bin\phpstan analyse .\src\hoge.php .\src\fuga.php

複数のファイルを解析する場合は、解析したいディレクトリ名を指定します。 解析したいディレクトリ名はスペース区切りで複数指定できます。

.\vendor\bin\phpstan analyse .\src

.\vendor\bin\phpstan analyse .\src .\tests

レベルを変更するには --level オプションを使用します。 --level オプション には、エイリアス（別名） -l オプションがあります。

.\vendor\bin\phpstan analyse -l 6 .\src

最大のレベルを設定する際には、エイリアス（別名）max が使用できます。 現状ではレベル 8 が最大ですが、今後 PHPStan がバージョンアップして、9 以上のレベルが新しく増えた場合でも、常に最大のレベルで動作させることができます。

.\vendor\bin\phpstan analyse -l max .\src

構成ファイルのフォーマットは、NEON です。 NEON は、YAMLと非常によく似ているため、YAML に慣れている方は簡単に NEON を作成することができると思います。

ここでは簡単な例だけ記載しておきます。

parameters:
	level: 6
	paths:
		- src
		- tests

どんな設定項目があるかは、ここでは記載しません。 あまりにも大量にありますので、英語ですが公式のドキュメントを見てもらった方が良いと思います。

• Config Reference | PHPStan

構成ファイルを使用する方法は2つあります。

.\vendor\bin\phpstan analyse -c .\custom_phpstan.neon

.\vendor\bin\phpstan analyse

PHPStan で自動的に読み込まれる構成ファイルは、phpstan.neon と phpstan.neon.dist の2つです。 通常は、phpstan.neon.dist の方を Git などのバージョン管理下に置き、phpstan.neon の方を .gitignore に追加します。 各ユーザーが phpstan.neon.dist を元にして、phpstan.neon を作成することで、 各環境内（各ユーザーのPCや、CIサーバーなど）で特定の設定を上書きできるようにします。 phpstan.neon と phpstan.neon.dist の両方のファイルがある場合に、phpstan.neon の方が優先して読み込まれるのはそのためです。

PHPStan の構成ファイルでは、複数のファイルから構成するための includes の項目があります。 そのため、phpstan.neon ファイルから、phpstan.neon.dist ファイルを includes の項目で読み込んで使用できます。

parameters:
	level: 6
	paths:
		- src
		- tests

includes:
	- phpstan.neon.dist

parameters:
	level: 8

	ignoreErrors:
		- '#Function pcntl_open not found\.#'

1つ目の方法は、PHP のコード上に PHPDocs として記述する方法です。 この方法は、ピンポイントで指定できるというメリットはありますが、大量に使用した場合は PHP のコードがコメントで汚れてしまうというデメリットがあります。 できるなら、後述の構成ファイルに記載する方法の方が良いでしょう。

使用するには、PHP のコメント（//、/* */、/** */のいずれでも可）の中で、下記のタグを使用します。

• @phpstan-ignore-line は、それが書かれたその行を無視します。
• @phpstan-ignore-next-line は、それが書かれたその次の行を無視します。

<?php

echo $foo; // @phpstan-ignore-line

/* @phpstan-ignore-next-line */
echo $foo;

2つ目の方法は、無視したいエラーを構成ファイルに記載することです。 構成ファイルの ignoreErrors 項目の下に、無視したいエラーを正規表現で追加することで、そのエラーを無視できます。 正規表現ですので、「|」「$」「.」「(」「)」などの特殊文字はエスケープする必要があるので注意です。

parameters:
	ignoreErrors:
		- '#Call to an undefined method [a-zA-Z0-9\\_]+::doFoo\(\)#'
		- '#Call to an undefined method [a-zA-Z0-9\\_]+::doBar\(\)#'

parameters:
	ignoreErrors:
		-
			message: '#Access to an undefined property [a-zA-Z0-9\\_]+::\$foo#'
			path: some/dir/SomeFile.php
		-
			message: '#Call to an undefined method [a-zA-Z0-9\\_]+::doFoo\(\)#'
			path: other/dir/DifferentFile.php
			count: 2 # optional
		-
			message: '#Call to an undefined method [a-zA-Z0-9\\_]+::doBar\(\)#'
			paths:
				- some/dir/*
				- other/dir/*
		- '#Other error to ignore everywhere#'

現在発生している全てのエラーの一覧をベースラインファイルに保存するには、--generate-baseline オプションを使用します。 ファイル名は --generate-baseline オプションのパラメーターとして指定することができます。 ファイル名が未指定の場合、ファイル名は phpstan-baseline.neon になります。 このベースラインファイルは、構成ファイルと同じ形式の NEON ファイルですので、手動で編集することも、再度生成しなおすこともできます。

.\vendor\bin\phpstan analyse --generate-baseline

.\vendor\bin\phpstan analyse --generate-baseline=basline.neon

ベースラインファイルを読み込むには、構成ファイルの includes の項目で、読み込むファイルを指定します。

includes:
	- phpstan-baseline.neon

parameters:
	# your usual configuration options

ベースラインファイルに記載されているエラーの個所のコードが修正されエラーが発生しなくなった場合、 ベースラインファイルにはエラーを無視する記載が残ったままになってしまい、コードと食い違ってしまうという状況が発生します。 ベースラインファイルから、修正された箇所のエラーを無視する記載を削除する必要があります。

この状況が発生した場合、PHPStan が通知してくれます。 もしこの通知が不要な場合は、構成ファイルで reportUnmatchedIgnoredErrors を false に設定することで、オフにすることができます。

includes:
	- phpstan-baseline.neon

parameters:
	reportUnmatchedIgnoredErrors: false

ルールレベルを上げるには、そのレベルでのエラーが 0 件になっているのが理想です。 しかしながら、大量に修正箇所がある場合、レベルが上がるまでかなりの時間を費やすことになります。 それはつまり、より高いレベルで見つかるようなエラーはずっと見逃している状態になることを意味します。

ベースラインを使用すると、その時点のエラーを全て無視することができますから、 低いレベルでの修正が全て終わるのを待たずに、一気にレベルを上げることが可能になります。 これにより、新しく変更されたコードには、より高いレベルでの厳密なチェックを適用することが可能です。

Composer スクリプトから実行した場合に、出力内容に色がちゃんとつかない場合があります。 その場合は、--ansi オプションを付けてみましょう。

{
	"name": "hoge/hoge",
	"require-dev": {
		"phpstan/phpstan": "^0.12.98"
	},
	"scripts": {
		"stan": "phpstan analyse --ansi"
	}
}