23日目：PHP_CodeSnifferの独自の規約を作ろう

2013年12月8日

明日はsugiさんです．

初めまして、RCC一回生のabcangです。主にRCCでは気ままにプログラミングしています。
現在、RCCの後期グループ活動ではPHPのLaravelというフレームワークを使って進捗管理SNSを作っています。
複数人でコーディングするときはコーディング規約を決めておくのが大切です。これを決めておくと、書き方が統一され、とてもコードが読みやすくなります。
PHPでは、コーディング規約に合っているかどうかを調べるのに、PHP_CodeSnifferを使用します。有名なフレームワークのコーディング規約はPHP_CodeSnifferに入っていたり、有志の人が公開してくれていたりします。
ここで、PHPのコーディング規約でよく用いられるPSR-2と見比べてみましょう。

PSR-2

<?php
class BaseController extends Controller
{
	protected function setupLayout()
	{
		if ( ! is_null($this->layout)) {
			$this->layout = View::make($this->layout);
		}
	}
}

Laravel

<?php
class BaseController extends Controller {
	protected function setupLayout()
	{
		if ( ! is_null($this->layout))
		{
			$this->layout = View::make($this->layout);
		}
	}
}

見てもらえばわかると思いますが、PSR-2と比べると、ifの後の波括弧が改行されていたり、classの後の波括弧が改行されていなかったりしています。当然、PSR2の規約ではLaravelのチェックはできません。Laravelの規約も公開されていますが、書き方が独特なためなのか最低限のチェックだけで厳密なチェックをしてくれません。具体的に言うと、その公開されている規約では上の例の書き方のどちらで試してもエラーがでません。これではあまり意味がありません。そのため、規約ファイルを自分で作らなければなりません。

基本的にはManual :: 独自の規約を作成するための手引きやManual :: A sample ruleset.xml file that describes all features of the formatを参考にすれば作ることができます。
ですが、ここでは独自の規約の作り方のポイントを説明したいと思います。
簡単に分けると、
①ベースになる規約をインクルード
②都合の悪いチェック項目を除外
③足りないチェック項目を補う
の3ステップになります。

①ベースになる規約をインクルード
ruleset.xmlにベースになる規約をインクルードします。

<rule ref=”PSR2″/>

のように書くとPSR2の規約が反映されるようになります。ただ、このままだとPSR2を直接使うことと同じなので、次のステップに移ります。

②都合の悪いチェック項目を除外
まずは作った規約でチェックしてみましょう

$ phpcs BaseController.php –standard=HOGE

3 | ERROR | Opening brace of a class must be on the line after the definition
6 | ERROR | Expected “if (…) {\n”; found “if (…)\n {\n”

この出力からはどこの規約を判定するプログラムでエラーを出しているのかわかりません。なので、”-s”オプションを付けて出力します。

$ phpcs BaseController.php –standard=HOGE

3 | ERROR | Opening brace of a class must be on the line after the definition
| | (PSR2.Classes.ClassDeclaration.OpenBraceNewLine)
6 | ERROR | Expected “if (…) {\n”; found “if (…)\n {\n”
| | (Squiz.ControlStructures.ControlSignature)

ご覧の通り、エラーを出してるプログラムが分かりました。では、エラーを出ないようにruleset.xmlを書き換えましょう。

<rule ref=”PSR2″>
<exclude name=”PSR2.Classes.ClassDeclaration”/>
<exclude name=”Squiz.ControlStructures.ControlSignature”/>
</rule>

これでエラーは出なくなりました。しかし、これではLaravelのコードでPSR2の書き方をしている場合もエラーを出してくれません。これでは効果が薄いので、間違っていたらエラーを出すようにしましょう。

③足りないチェック項目を補う

規約を追加するには3つの方法があります。まず1つ目はすでにあるプログラムを使用することです。
PHP_CodeSnifferにはコーディング規約や汎用的に使われるプログラムが含まれています。それをruleset.xmlに書くことで簡単に使うことができます。

<rule ref=”PSR2″>
<exclude name=”PSR2.Classes.ClassDeclaration”/>
<exclude name=”Squiz.ControlStructures.ControlSignature”/>
</rule>
<rule ref=”Generic.PHP.LowerCaseKeyword”/>

プログラムの名前や中身にあるコメントを見ることでどんな機能を持っているか判断でき、チェックしたいものだけを規約に追加することができます。

CodeSniffer/Standards/Generic/Sniffs/PHP/LowerCaseKeywordSniff.php

というファイルを追加したいときは

<rule ref=”Generic.PHP.LowerCaseKeyword”/>

のように書きます。
この方法ではifやclassの部分をうまくチェックしてくれるものがなかったので、次の方法に移りたいと思います。

2つ目はネットからコードを探す方法です。冒頭にも言ったように、有志の人が独自の規約を公開しています。これを利用することで簡単に規約に追加できます。
規約プログラムのコードやコメントの一部を使ってgithubなどで検索すると、似たようなルールのプログラムがたくさん出てきます。それをダウンロードし、正しいフォルダに配置して、ファイルパスに合うようにClass名を調整してあげればルールを適用できます。実際に、上の例のifの後の波括弧のルールプログラムはgithubで見つけました。

3つ目は、自分で書くことです。既にあるプログラムを改変して使うのがオススメです。自分で1から書くのはしんどいと思います。
上の例のclassの後の波括弧のルールプログラムは他のプログラムを元に改変して作ることになりました。
書き方はマニュアルのページに書いてあるので割愛させてもらいます。

ということで、独自の規約の作り方のポイントでした。コーディング規約を守って、素晴らしいコーディングライフを送りましょう！