phpcsでPSR-2コーディング規約チェックを行う

カテゴリ: composer, PHP, phpcs

昔のPHPは、コーディング規約がPear, Zend, CakePHP, Symfony, WordPressなど、フレームワークごとに異なっており複数ライブラリを導入した場合に、プロジェクト全体でコーディング規約を統一させることが困難でした。

ですが、最近ではPHP-FIG(PHP Framework Interop Group)が制定したPSR-2コーディング規約が事実上のPHP標準規約となっており、各フレームワークもこの規格を順守する流れになっています。PHP-FIGによるコーディング規約は、2017年4月現在PSR-1: Basic Coding StandardPSR-2: Coding Style Guideが存在していますが、PSR-2の最初のルールは"PSR-1を順守すること"なので、PSR-2準拠であることを確認すればOKです。

プロジェクトで作成したコードもPSR-2コーディング規約に合わせたくなるのですが、規約に準拠しているかを目視でチェックするのは非常に手間がかかります。このような場合、phpcs(PHP CodeSniffe)を使用することで、コーディング規約チェックを機械的に行うことができます。

本記事ではphpcsを使用して、自分が作成したプログラムに対してPSR-2コーディング規約に準拠しているかチェックを行ってみます。

テスト対象のプログラムを作成する

まずは、コーディング規約をチェックする対象のプログラムを作成します。今回はsrcディレクトリを作成したうえで、srcディレクトリの中にプログラムを作ります(ここでは説明のために、あえてPSR-2規約から逸脱したプログラムを書いています)。

mkdir src
# src/test.phpを作成
<?php
function sayHello($name) {
    echo "hello {$name}.\n";
}

sayHello("alice");

作成したら、phpコマンドで、作ったプログラムが動作することを確認します

php src/test.php
hello alice.

コーディング規約チェックツールのphpcsをインストール

次にphpcsプログラムをインストールします。phpcsはcomposerを利用して、下記のコマンドでインストールが可能です。

composer require squizlabs/php_codesniffer

phpcsの動作確認

作成したプログラムsrc/test.phpに対して、phpcsでコーディング規約のチェックを行ってみます。
ここでは、エラー内容の確認は後回しにしてphpcs.batコマンドで何らかのエラーが出力されればOKです(ここで出力される内容はPSR-2の規約チェック結果ではありません)。

vendor\bin\phpcs.bat  src/test1.php

----------------------------------------------------------------------
FOUND 6 ERRORS AFFECTING 4 LINES
----------------------------------------------------------------------
 1 | ERROR | [x] End of line character is invalid; expected "\n" but
   |       |     found "\r\n"
 2 | ERROR | [ ] Missing file doc comment
 4 | ERROR | [ ] Missing function doc comment
 4 | ERROR | [x] Opening brace should be on a new line
 9 | ERROR | [x] Space after opening parenthesis of function call
   |       |     prohibited
 9 | ERROR | [x] Expected 0 spaces before closing bracket; 1 found
----------------------------------------------------------------------
PHPCBF CAN FIX THE 4 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

上記の出力でもよいのですが、メッセージが改行されて見づらいのが気になる場合は--report-widthオプションを使って行の幅を広げると見やすいです。

vendor\bin\phpcs.bat src/test1.php --report-width=200

FILE: C:\project\src\test1.php
----------------------------------------------------------------------------------
FOUND 6 ERRORS AFFECTING 4 LINES
----------------------------------------------------------------------------------
 1 | ERROR | [x] End of line character is invalid; expected "\n" but found "\r\n"
 2 | ERROR | [ ] Missing file doc comment
 4 | ERROR | [ ] Missing function doc comment
 4 | ERROR | [x] Opening brace should be on a new line
 9 | ERROR | [x] Space after opening parenthesis of function call prohibited
 9 | ERROR | [x] Expected 0 spaces before closing bracket; 1 found
----------------------------------------------------------------------------------
PHPCBF CAN FIX THE 4 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------

これで、phpcsの動作確認は完了です。

phpcsによるPSR-1, PSR-2の規約チェック

それでは、いよいよPSR規約のコーディング違反をチェックします。まずはPSR-1のコーディング規約違反をチェックします。
チェックする対象の規約は、"--standard"オプションで指定可能です。

PSR-1の規約は非常に基本的な事項だけですので、指摘されたのは1項目だけでした。

vendor\bin\phpcs.bat  src/test1.php --report-width=120 --standard=PSR1

FILE: C:\project\src\test1.php
------------------------------------------------------------------------------------------------------------------------
FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE
------------------------------------------------------------------------------------------------------------------------
 1 | WARNING | A file should declare new symbols (classes, functions, constants, etc.) and cause no other side effects,
   |         | or it should execute logic with side effects, but should not do both. The first symbol is defined on
   |         | line 4 and the first side effect is on line 9.
------------------------------------------------------------------------------------------------------------------------

次に、PSR-2規約のコーディング違反をチェックします。
前述の通りPSR-2はPSR-1を包含しているため、先ほど出力されたエラーはこちらでも出力されています。

vendor\bin\phpcs.bat  src/test1.php --report-width=120 --standard=PSR2

FILE: C:\project\src\test1.php
------------------------------------------------------------------------------------------------------------------------
FOUND 7 ERRORS AND 1 WARNING AFFECTING 3 LINES
------------------------------------------------------------------------------------------------------------------------
 1 | WARNING | [ ] A file should declare new symbols (classes, functions, constants, etc.) and cause no other side
   |         |     effects, or it should execute logic with side effects, but should not do both. The first symbol is
   |         |     defined on line 4 and the first side effect is on line 9.
 1 | ERROR   | [x] End of line character is invalid; expected "\n" but found "\r\n"
 4 | ERROR   | [x] Expected 0 spaces between opening bracket and argument "$name"; 1 found
 4 | ERROR   | [x] Expected 0 spaces between argument "$name" and closing bracket; 1 found
 4 | ERROR   | [x] Opening brace should be on a new line
 9 | ERROR   | [x] Space after opening parenthesis of function call prohibited
 9 | ERROR   | [x] Expected 0 spaces before closing bracket; 1 found
 9 | ERROR   | [x] Expected 1 newline at end of file; 0 found
------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 7 MARKED SNIFF VIOLATIONS AUTOMATICALLY
------------------------------------------------------------------------------------------------------------------------

指摘された項目の修正

それでは、出力されたエラーメッセージを見ながらPSR-2コーディング規約に違反している内容を直していきます。慣れないうちは、1つ直すごとにphpcsを再実行していくと規約違反がどこなのか把握しやすいです。

ちなみに前述のエラーメッセージの意味は下記のような感じです。

End of line character is invalid; expected "\n" but found "\r\n"
改行文字が、本来はLFであることを期待しているが、CR+LFになっている
Expected 0 spaces between opening bracket and argument "$name"; 1 found
関数の引数の前に余計なスペースがある
Expected 0 spaces between argument "$name" and closing bracket; 1 found
関数の引数の後に余計なスペースがある
Opening brace should be on a new line
関数の開始の"{"カッコは、別の行に書く必要がある
Space after opening parenthesis of function call prohibited
Expected 0 spaces before closing bracket; 1 found
閉じカッコの後にスペースが不要だが、スペースが1文字あった
Expected 1 newline at end of file; 0 found
ファイルの最後は空行が1行必要だが、0行だった

すべて修正を行いphpcsを実行してもエラーが出なければ、このコードはPSR-2規約に沿っていることが確認できた状態になります。

独自のコーディング規約を設定ファイルに保存する

モダンなPHPシステム開発の理想としては、PSR-2コーディング規約に順守したソースを書く事ですが、プロジェクトの事情によっては一部の規約のみ規約を除外させたり、追加で他のチェックを行いたい場合があります。phpcsは、phpcs.batコマンドを実行した作業フォルダにphpcs.xmlファイルがある場合、このファイルを設定ファイルとみなして、規約チェックを行います。

先ほど指定した--standard=PSR2ですが、具体的なチェックルールはphpcsのインストール先にある下記のファイルで定義されています。

vendor\squizlabs\php_codesniffer\
  CodeSniffer\
    Standards\
      PSR2\ruleset.xml

このruleset.xmlを参考にして独自のルールセットを作成すれば、プロジェクト独自のカスタマイズされたコーディング規約をチェックすることができます。

こちらもおススメ

One thought on “phpcsでPSR-2コーディング規約チェックを行う

コメントを残す

メールアドレスが公開されることはありません。