目次
phpcs を使って、他のルールセットにはない、独自のルールを設定する方法を調べた。
存在するルールセットを組み合わせる
そもそも、存在しているルールセットを組み合わせたり、無効にしたりするには、 composer を使ってパッケージを入れるなどして xml ファイルに記載をしていけば OK 。 これは GitHub の Wiki にもやり方が記載されている。
Coding Standard Tutorial · squizlabs/PHP_CodeSniffer Wiki
xml ファイルの例
<?xml version="1.0"?>
<ruleset name="oreore_ruleset">
<description>名前空間は無くてもいいよ</description>
<rule ref="PSR2">
<exclude name="PSR1.Classes.ClassDeclaration.MissingNamespace" />
</rule>
</ruleset>
コマンドの例
$ phpcs -n --colors --standard="oreore_ruleset.xml" src/調べたのはこれではじゃないよ
自分で 1 からルールを定義する
こちらも GitHub の Wiki 、同じページ（Coding Standard Tutorial）にも書いてある。 Creating the Sniff の項目。
が、ちょっとトラップがあって、 Creating the Sniff の項目だけ読んで進めると、足りないものがいろいろあって NG 。1からルールを定義するときにも xml ファイルは必要だった。
それを読みながら試しに作ってみたのがこれ。
sters/phpcs-myruleset-test: Create phpcs sniffer test repo.
実際に触ってみて、いくつかの制約があるっぽい（というか書いてある）
- ルールを格納するサブディレクトリを作らないといけない
- ファイル名の末尾が Sniff.php でないといけない
- PHP_CodeSniffer\Sniffs\Sniff インタフェースを利用する
- register と process メソッドを実装する
個別にもう少し詳しく深掘りする。
ルールを格納するサブディレクトリを作らないといけない
こんな感じで掘ると良さそう。 ルールセット名の下に Sniffs という名前にすると、自分で設定しているルールセットだよ～的な意味になるっぽい。
MyRule/Sniffs/HogeSniff.php
phpcs の実装としてはこのあたりにそう書いてあるように見える。 PHP_CodeSniffer/Ruleset.php at master · squizlabs/PHP_CodeSniffer
で、作ったディレクトリと同じ階層に xml ファイルを置く。中身は説明書き程度で、もし他のルールを継承したものを作っていく場合にはここに書き足していくと良いっぽい。
MyRule/rule.xml
<?xml version="1.0"?>
<ruleset name="MyRule">
<description>MyRule Coding Standards</description>
</ruleset>
アプリケーションと同じところに Sniffer は入れないと思うので（関心の分離的にも別で管理しよう！）、別管理する気持ちで作っていくと良いと思う。
ファイル名の末尾が Sniff.php でないといけない
phpcs が Sniff.php でファイルを探している。実装はこのあたり。
PHP_CodeSniffer/Ruleset.php at master · squizlabs/PHP_CodeSniffer
なので、ルールを書いていくファイルは HogeSniff.php のようなファイル名でないといけない。
MyRule/Sniffs/HogeSniff.php
PHP_CodeSniffer\Sniffs\Sniff インタフェースを利用する
このあたりからは、ぼくの試した実装とにらめっこしてみたほうがいいかもしれない。
これは phpcs の Wiki にも書いてあるものと同じ、ハッシュコメントを警告するための Sniff 。
phpcs-myruleset-test/DisallowHashCommentsSniff.php at master · sters/phpcs-myruleset-test
インタフェースの利用については特にいうこともないので、はい。
register と process メソッドを実装する
引き続き、ハッシュコメントを警告するための Sniff を見ながら。
phpcs では対象となった php ファイル（あるいは他のファイルも指定できる）に対して、トークナイザを実行し、指定されたトークンに対してのみ process メソッドが動くように作られている。 その指定されたトークンを register メソッドで指定する。こういう感じで。
public function register()
{
return [
T_COMMENT
];
}
トークンの一覧は php.net の方にある。
php.net のリストを見ると T_COMMENT は 「 // or #, and /* */ 」にあたると書いてある。 これでコメントのトークンに限定して process メソッドを実行できる。
process メソッドはこんな感じで書いている。
public function process(File $phpcsFile, $stackPtr)
{
$tokens = $phpcsFile->getTokens();
if ($tokens[$stackPtr]['content']{0} === '#') {
$error = 'Hash comments are prohibited; found %s';
$data = [trim($tokens[$stackPtr]['content'])];
$phpcsFile->addError($error, $stackPtr, 'Found', $data);
}
}
$phpcsFile は PHP_CodeSniffer\Files\File クラスのインスタンスで、今はどのファイルを対象にしているか、そのファイルのトークンは、といった情報が入っている。
$stackPtr はトークンスタックのうち現在の位置を示す int 。 register で指定したトークンが見つかった位置になる。当然のことながら 1 ファイルで複数見つかることもあるので、そのときは毎回 process メソッドが呼ばれるようだ。
$phpcsFile->getTokens() でトークンの一覧を取ることができ、これはトークンの二次元配列になっている。なので $stackPtr で参照することで、現在の位置のトークンが分かる。
トークンは以下のような形式で表現されている。
array(8) {
["type"]=>
string(9) "T_COMMENT"
["code"]=>
int(377)
["content"]=>
string(8) "# echo
"
["line"]=>
int(3)
["column"]=>
int(1)
["length"]=>
int(6)
["level"]=>
int(0)
["conditions"]=>
array(0) {
}
}
そのトークンが、コード中の何行目にあって～、どのネストレベルで～、とかとか。このうち content に着目すると、そのトークンが持っている中身が見られる。
コメントの場合はコメント自体がまるっとトークンになるので、そのうちの先頭 1 文字をみて # だったらエラーを出すことで、ハッシュコメントを警告する Sniff の出来上がり。
自作のルールも phpcbf で自動でなおるようにしたい
お試したリポジトリには入れていなかったのだが addFixableError と fixer->replaceToken を使うことで出来るっぽい。
PHP_CodeSniffer/ClassDeclarationSniff.php at master · squizlabs/PHP_CodeSniffer
$fix = $phpcsFile->addFixableError($error, $stackPtr, 'SpaceBeforeKeyword', $data);
if ($fix === true) {
$phpcsFile->fixer->replaceToken(($stackPtr - 1), ' ');
}
複雑なルールを作っていきたい
もしかしたら場合によって、もっと複雑なルールを設定していきたいような場合もあるのでは…？ そんなときどうするんだろうなあと思ったけれど、結局のところは気合で処理を書いていかないといけない（そりゃそうだ）
それは phpcs に含まれる PSR のルールを見てもそうだし Packagist にあるルールセットを見てもみんながんばってるのが分かる。
例えば PSR-2 のクラス定義に関する Sniff 。 PHP_CodeSniffer/ClassDeclarationSniff.php at master · squizlabs/PHP_CodeSniffer
「 1 つ前のトークンが空白で、改行で、その前が abstract か final だったらエラー！」とかそういう。
例えば… とおもって Packagist みていたら phpcs でセキュリティチェックしてくれる君があった。 FloeDesignTechnologies/phpcs-security-audit
その中に簡易的に XSS のチェックをしてくれるのがあるが、やっぱり頑張る phpcs-security-audit/EasyXSSSniff.php at master · FloeDesignTechnologies/phpcs-security-audit
とはいえ、全部書くのもあれなので、 phpcs 側で用意されているユーティリティメソッドだったり、自分で便利に使うものを用意すると Sniff 本体が簡潔に書けて良さそうだ。
例えば処理の中や後ろにコメントを書くようなあれを警告する Sniff を作ってみたのがこんな感じ。
phpcs-myruleset-test/DisallowInlineCommentsSniff.php at master · sters/phpcs-myruleset-test
public function process(File $phpcsFile, $stackPtr)
{
$this->tokens = $phpcsFile->getTokens();
$tokenPrev = $this->findSomethingFirstOnLine($phpcsFile, $stackPtr);
$tokenNext = $this->findSomethingLastOnLine($phpcsFile, $stackPtr);
if ($tokenPrev !== false || $tokenNext !== false) {
$message = "Disallow Inline comments.";
$errorCode = 'inline_comments';
$placeholder = [];
$phpcsFile->addError($message, $stackPtr, $errorCode, $placeholder);
}
}
findSomething.. は同じ行の前後に、自分以外の別トークンがいるかを探すメソッド。 findFirstOnLine というのが File クラスのメソッドにはあるが、微妙にそういう意図じゃないんだよ！というところだったので、参考にしつつ作ったのがコレ。行の情報があるので、ぐるぐるして、同じ行で別トークンがあるかな？を探しているだけで、特別難しいことは何もしていないとは思う。
おわり
特定のキーワード、特定の処理方法を警告するようなものは簡単に作れそうなので、余力があれば、チーム独自ルールみたいなものを phpcs に掛けられるようにすると、レビューコストが下がったり(?)、変な記述が生まれにくくて、いいなあと思ったとさ。
命名規則のようなちょっとむずかしそうなルールも、頑張ったら実装していくことは出来るので、そういうのを統一していきたいんだよね、みたいな事象のときに活用できそうだ。