高度な使用法
有効なファイル拡張子の指定
デフォルトでは、PHP_CodeSniffer がチェックするのは拡張子が .inc か .php のファイルのみです。 これだけでは、PHP_CodeSniffer があなたの使用するファイルをすべて網羅できないかもしれません。 また逆の場合もあるでしょう。 PHP_CodeSniffer では、コマンドライン引数 --extensions によって有効なファイル拡張子を指定することができます。 拡張子は、カンマで区切って指定します。
.php ファイルのみのチェック
$ phpcs --extensions=php /path/to/code
.php、.inc および .lib ファイルのみのチェック
$ phpcs --extensions=php,inc,lib /path/to/code
PHP_CodeSniffer に対して ディレクトリ全体ではなく特定のファイルをチェックするよう指示した場合は、 そのファイルの拡張子を無視します。 有効な拡張子ではない場合や拡張子がない場合でも、そのファイルをチェックします。
次の例では、コマンドライン引数 --extensions で .php ファイルのみをチェックするようにしていますが、 main.inc はチェックされます。
ファイルを直接指定した場合は拡張子指定が無視される
$ phpcs --extensions=php /path/to/code/main.inc
ファイル名の直接指定によって拡張子を無視するという PHP_CodeSniffer の機能は、 拡張子のないファイルをチェックするための唯一の方法となります。 ディレクトリ内のすべてのファイルをチェックする場合、 拡張子のないファイルは無視されてしまうので、 それらは個別に指定する必要があります。
ファイルやフォルダの無視
PHP_CodeSniffer で大量のファイルを処理する際に、 特定のファイルやフォルダは処理をスキップしたいということもあるでしょう。 コマンドライン引数 --ignore を使用すると、 PHP_CodeSniffer に処理をスキップさせるファイル名やフォルダ名のパターンを指定することができます。
次の例では、PHP_CodeSniffer がパッケージの tests ディレクトリおよび data ディレクトリをスキップするように指定しています。 これは、PEAR パッケージをチェックする際に テストファイルやデータファイルまではチェックする必要はないという場合に便利です。
テストファイルやデータファイルの無視
$ phpcs --ignore=*/tests/*,*/data/* /path/to/code
タブのスペースへの置き換え
PHP_CodeSniffer 用に書かれた sniff のほとんどは、 字下げや位置調整にタブを使用することをサポートしていません。 自分で sniff を作成する際にはスペースではなくタブをチェックするようにすることもできますが、 ファイルをチェックする前に、タブをスペースに変換させるよう PHP_CodeSniffer に指定することもできます。 こうすることで、スペースを想定している既存の sniff でタブを含むファイルを使用することができます。
次の例では、ファイルをチェックする前に PHP_CodeSniffer がすべてのタブを 1 個から 4 個のスペースに置き換えます。 スペースの量は、そのタブが字下げをするカラムによって決まります。
タブからスペースへの変換
$ phpcs --tab-width=4 /path/to/code
XML でのレポートの表示
PHP_CodeSniffer は、結果を XML 形式で出力することもできます。 これを使用すると、自作のスクリプトで結果を利用するのが簡単になります。 XML 形式のレポートを表示するには、コマンドライン引数 --report=xml を指定します。出力は、次のようになります。
PHP_CodeSniffer の XML 出力の例
$ phpcs --report=xml /path/to/code
<?xml version="1.0" encoding="UTF-8"?>
<phpcs version="1.0.0">
<file name="/path/to/code/myfile.php" errors="5" warnings="1">
<error line="2" column="1">Missing file doc comment</error>
<error line="20" column="43">PHP keywords must be lowercase; expected "false" but found "FALSE"</error>
<error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error>
<warning line="47" column="20">Equals sign not aligned with surrounding assignments</warning>
<error line="51" column="4">Missing function doc comment</error>
<error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</error>
</file>
</phpcs>
完全なレポートだけでなく、警告を非表示にしたレポートも作成することができます。 この場合は、コマンドライン引数 -n を使用します。
PHP_CodeSniffer の XML 出力で、警告を出力しない例
$ phpcs -n --report=xml /path/to/code
<?xml version="1.0" encoding="UTF-8"?>
<phpcs version="1.0.0">
<file name="/path/to/code/myfile.php" errors="5" warnings="0">
<error line="2" column="1">Missing file doc comment</error>
<error line="20" column="43">PHP keywords must be lowercase; expected "false" but found "FALSE"</error>
<error line="47" column="1">Line not indented correctly; expected 4 spaces but found 1</error>
<error line="51" column="4">Missing function doc comment</error>
<error line="88" column="1">Line not indented correctly; expected 9 spaces but found 6</error>
</file>
</phpcs>
Checkstyle でのレポートの表示
PHP_CodeSniffer は、結果を Checkstyle 形式の XML で出力することができます。これを使用すると、 Checkstyle 形式をサポートしているアプリケーションやスクリプトで その出力結果を使用することができます。Checkstyle 形式のレポートを表示するには、 コマンドライン引数 --report=checkstyle を使用します。出力は、次のようになります。
PHP_CodeSniffer の Checkstyle 出力の
$ phpcs --report=checkstyle /path/to/code
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="1.0.0">
<file name="/path/to/code/myfile.php">
<error line="2" column="1" severity="error" message="Missing file doc comment"/>
<error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected "false" but found "FALSE""/>
<error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/>
<error line="47" column="20" severity="warning" message="Equals sign not aligned with surrounding assignments"/>
<error line="51" column="4" severity="error" message="Missing function doc comment"/>
<error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/>
</file>
</checkstyle>
As with the full report, you can suppress the printing of warnings with the -n command line argument.
Sample PHP_CodeSniffer Checkstyle output with no warnings
$ phpcs -n --report=checkstyle /path/to/code
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="1.0.0">
<file name="/path/to/code/myfile.php">
<error line="2" column="1" severity="error" message="Missing file doc comment"/>
<error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected "false" but found "FALSE""/>
<error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1"/>
<error line="51" column="4" severity="error" message="Missing function doc comment"/>
<error line="88" column="1" severity="error" message="Line not indented correctly; expected 9 spaces but found 6"/>
</file>
</checkstyle>
CSV でのレポートの表示
PHP_CodeSniffer は、結果を CSV 形式のレポートとして出力することもできます。 これを使用すると、自作のスクリプトで結果を利用するのが簡単になります。 CSV 形式のレポートを表示するには、コマンドライン引数 --report=csv を使用します。出力は、次のようになります。
PHP_CodeSniffer の CSV 出力の例
$ phpcs --report=csv /path/to/code
File,Line,Column,Severity,Message
"/path/to/code/myfile.php",2,1,error,"Missing file doc comment"
"/path/to/code/myfile.php",20,43,error,"PHP keywords must be lowercase; expected \"false\" but found \"FALSE\""
"/path/to/code/myfile.php",47,1,error,"Line not indented correctly; expected 4 spaces but found 1"
"/path/to/code/myfile.php",47,20,warning,"Equals sign not aligned with surrounding assignments"
"/path/to/code/myfile.php",51,4,error,"Missing function doc comment"
"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6"
完全なレポートだけでなく、警告を非表示にしたレポートも作成することができます。 この場合は、コマンドライン引数 -n を使用します。
PHP_CodeSniffer の CSV 出力で、警告を出力しない例
$ phpcs -n --report=csv /path/to/code
File,Line,Column,Severity,Message
"/path/to/code/myfile.php",2,1,error,"Missing file doc comment"
"/path/to/code/myfile.php",20,43,error,"PHP keywords must be lowercase; expected \"false\" but found \"FALSE\""
"/path/to/code/myfile.php",47,1,error,"Line not indented correctly; expected 4 spaces but found 1"
"/path/to/code/myfile.php",51,4,error,"Missing function doc comment"
"/path/to/code/myfile.php",88,1,error,"Line not indented correctly; expected 9 spaces but found 6"
CSV 出力の最初の行は、情報の並び順を表します。 CSV 出力を使用する際は、このヘッダ行の情報をもとにしてデータを取得するようにしましょう。 CSV の書式が替わったり、新たな情報が追加されたりする可能性もあります。
設定オプションの指定
PHP_CodeSniffer には、いくつかの設定オプションがあります。 コーディング規約によっては、事前にオプションを設定しておかないと使用できないものもあります。 設定オプションの完全な一覧はこちらです。
オプションを設定するには、コマンドライン引数 --config-set を使用します。
オプションの設定
$ phpcs --config-set <option> <value>
設定オプションの削除
PHP_CodeSniffer では、任意の設定オプションを削除してデフォルト値に戻すことができます。 設定オプションの全一覧はこちらです。
設定オプションを削除するには、コマンドライン引数 --config-delete を使用します。
設定オプションの削除
$ phpcs --config-delete <option>
設定オプションの閲覧
現在設定されているオプションの内容を見るには、コマンドライン引数 --config-show を使用します。
設定オプションの閲覧
$ phpcs --config-show
Array
(
[default_standard] => PEAR
[zend_ca_path] => /path/to/ZendCodeAnalyzer
)
詳細なトークナイザの出力
この機能は、デバッグのためにのみ用意されているものです。 この機能を使用すると、画面に表示される内容が大幅に増え、 またスクリプトの実行時間も大幅に長くなってしまいます。
PHP_CodeSniffer は、出力内容をいくつかのレベルにわけています。 レベル 2 (コマンドライン引数 -vv で指定します) は、レベル 1 (ファイルごとのトークン数および行数、そして実行所要時間) と同様の情報をすべて含み、さらに詳細なトークナイザの出力も表示します。
PHP_CodeSniffer のトークナイザの出力は、 スコープマップ および レベルマップ が徐々に作成されていく段階を示します。
スコープマップ
スコープマップについては、例を見ていただくのが一番わかりやすいでしょう。 次のようなファイルについて、
<?php
if ($condition) {
echo 'Condition was true';
}
?>
スコープマップの出力はこのようになります。
スコープマップの出力例
*** START SCOPE MAP ***
Start scope map at 1: T_IF => if
Process token 2 []: T_WHITESPACE =>
Process token 3 []: T_OPEN_PARENTHESIS => (
Process token 6 []: T_WHITESPACE =>
Process token 7 []: T_OPEN_CURLY_BRACKET => {
=> Found scope opener for 1 (T_IF)
Process token 8 [opener:7;]: T_WHITESPACE => \n
Process token 9 [opener:7;]: T_WHITESPACE =>
Process token 10 [opener:7;]: T_ECHO => echo
Process token 11 [opener:7;]: T_WHITESPACE =>
Process token 12 [opener:7;]: T_CONSTANT_ENCAPSED_STRING => 'Condition was true'
Process token 13 [opener:7;]: T_SEMICOLON => ;
Process token 14 [opener:7;]: T_WHITESPACE => \n
Process token 15 [opener:7;]: T_CLOSE_CURLY_BRACKET => }
=> Found scope closer for 1 (T_IF)
*** END SCOPE MAP ***
上のスコープマップには、そのファイルについての次のような情報が含まれます。
-
スコープトークン if が、トークン 1 で見つかりました (トークン 0 は PHP の開始タグとなります)。
-
if 文の開始部である開き波括弧が、トークン 7 で見つかりました。
-
if 文の終了部である閉じ波括弧が、トークン 15 で見つかりました。
-
トークン 8 から 15 はすべて、トークン 7 (開き波括弧) で開かれたスコープに含まれます。これは、これらのトークンがすべて if 文の内部にあることを表します。
スコープマップの出力の最大の目的は、PHP_CodeSniffer のスコープマップをデバッグすることです。これは、 ファイルのチェックをきちんと行うために非常に重要なことです。 しかしそれだけではなく、特定のトークンの型を調べるためにも使用できます。 たとえば、開き波括弧のトークン型が何であるかを忘れてしまった場合は、 トークンマップの出力を見れば、それが T_OPEN_CURLY_BRACKET であって T_OPEN_CURLY_BRACE ではないことがわかります。
レベルマップ
レベルマップについては、例を見ていただくのが一番わかりやすいでしょう。 次のようなファイルについて、
<?php
if ($condition) {
echo 'Condition was true';
}
?>
レベルマップの出力はこのようになります。
レベルマップの出力例
*** START LEVEL MAP ***
Process token 0 on line 1 [lvl:0;]: T_OPEN_TAG => <?php\n
Process token 1 on line 2 [lvl:0;]: T_IF => if
Process token 2 on line 2 [lvl:0;]: T_WHITESPACE =>
Process token 3 on line 2 [lvl:0;]: T_OPEN_PARENTHESIS => (
Process token 4 on line 2 [lvl:0;]: T_VARIABLE => $condition
Process token 5 on line 2 [lvl:0;]: T_CLOSE_PARENTHESIS => )
Process token 6 on line 2 [lvl:0;]: T_WHITESPACE =>
Process token 7 on line 2 [lvl:0;]: T_OPEN_CURLY_BRACKET => {
=> Found scope opener for 1 (T_IF)
* level increased *
* token 1 (T_IF) added to conditions array *
Process token 8 on line 2 [lvl:1;conds;T_IF;]: T_WHITESPACE => \n
Process token 9 on line 3 [lvl:1;conds;T_IF;]: T_WHITESPACE =>
Process token 10 on line 3 [lvl:1;conds;T_IF;]: T_ECHO => echo
Process token 11 on line 3 [lvl:1;conds;T_IF;]: T_WHITESPACE =>
Process token 12 on line 3 [lvl:1;conds;T_IF;]: T_CONSTANT_ENCAPSED_STRING => 'Condition was true'
Process token 13 on line 3 [lvl:1;conds;T_IF;]: T_SEMICOLON => ;
Process token 14 on line 3 [lvl:1;conds;T_IF;]: T_WHITESPACE => \n
Process token 15 on line 4 [lvl:1;conds;T_IF;]: T_CLOSE_CURLY_BRACKET => }
=> Found scope closer for 7 (T_OPEN_CURLY_BRACKET)
* token T_IF removed from conditions array *
* level decreased *
Process token 16 on line 4 [lvl:0;]: T_WHITESPACE => \n
Process token 17 on line 5 [lvl:0;]: T_CLOSE_TAG => ?>\n
*** END LEVEL MAP ***
上のレベルマップには、そのファイルについての次のような情報が含まれます。
-
スコープを開始する開き波括弧が、トークン 7 で見つかりました。これは、トークン 1 で定義された if 文のスコープを開始します。
-
トークン 8 から 15 はすべて、トークン 7 (開き波括弧) で開かれたスコープに含まれます。これらのすべてのトークンはレベル 1 です。つまり、これらはひとつのスコープ条件で囲まれているということです。すべて、ひとつの条件 (if 文) に囲まれています。
レベルマップの一般的な使用法は、字下げのルールを定義したり (たとえばレベル 4 の深さは空白 16 文字で字下げしなければならないなど) 特定のトークンが特定のスコープ内にあるかどうかを定義したり (たとえば、キーワード function がクラスのスコープにあれば、それをメソッドと判断するなど) することです。
詳細なトークン処理結果の出力
この機能は、デバッグのためにのみ用意されているものです。 この機能を使用すると、画面に表示される内容が大幅に増え、 またスクリプトの実行時間も大幅に長くなってしまいます。
PHP_CodeSniffer は、出力内容をいくつかのレベルにわけています。 レベル 3 (コマンドライン引数 -vvv で指定します) は、レベル 1 (ファイルごとのトークン数および行数、そして実行所要時間) およびレベル 2 (トークナイザの出力) と同様の情報をすべて含み、さらに sniff の実行時のトークン処理結果を出力します。
トークン処理結果については、例を見ていただくのが一番わかりやすいでしょう。 次のようなファイルについて、
<?php
if ($condition) {
echo 'Condition was true';
}
?>
トークン処理結果の出力は次のようになります。
トークン処理結果の出力例
*** START TOKEN PROCESSING ***
Process token 0: T_OPEN_TAG => <?php\n
Processing PEAR_Sniffs_Commenting_FileCommentSniff... DONE in 0.001 seconds
Processing PEAR_Sniffs_Files_LineLengthSniff... DONE in 0.0004 seconds
Processing PEAR_Sniffs_PHP_DisallowShortOpenTagSniff... DONE in 0.0001 seconds
Process token 1: T_IF => if
Processing PEAR_Sniffs_ControlStructures_ControlSignatureSniff... DONE in 0.0008 seconds
Processing PEAR_Sniffs_WhiteSpace_ScopeClosingBraceSniff... DONE in 0.0248 seconds
Processing PEAR_Sniffs_WhiteSpace_ScopeIndentSniff... DONE in 0.0004 seconds
Process token 2: T_WHITESPACE =>
Process token 3: T_OPEN_PARENTHESIS => (
Process token 4: T_VARIABLE => $condition
Process token 5: T_CLOSE_PARENTHESIS => )
Process token 6: T_WHITESPACE =>
Process token 7: T_OPEN_CURLY_BRACKET => {
Process token 8: T_WHITESPACE => \n
Process token 9: T_WHITESPACE =>
Process token 10: T_ECHO => echo
Process token 11: T_WHITESPACE =>
Process token 12: T_CONSTANT_ENCAPSED_STRING => 'Condition was true'
Process token 13: T_SEMICOLON => ;
Process token 14: T_WHITESPACE => \n
Process token 15: T_CLOSE_CURLY_BRACKET => }
Process token 16: T_WHITESPACE => \n
Process token 17: T_CLOSE_TAG => ?>\n
*** END TOKEN PROCESSING ***
処理したトークンがすべて、その ID や型そして内容とともに表示されます。 各トークンについて、そのトークン上で実行したすべての sniff と実行所要時間が表示されます。
たとえば、上の出力を見ると、トークン 1 (if キーワード) に対しては ControlSignature、ScopeClosingBrace および ScopeIndent の 3 つの sniff が実行されたことがわかります。 それぞれ短時間で処理されていますが、一番時間がかかったのは ScopeClosingBrace で、トークンを処理するのに 0.0248 秒を要しています。
もうひとつ、上の出力からわかる興味深いことは、 ファイル全体の中で sniff が実行されたトークンが トークン 0、トークン 1 のふたつだけであるということです。 これは、PHP_CodeSniffer にとっては通常の挙動です。 というのも、たいていの sniff は特定のトークンを待ちうけ、 それに続くトークンとあわせて処理するからです。
たとえば、ScopeIndentSniff は、if 文のトークンでしか実行されませんが、実際には if 文の内部のすべての行についての字下げをチェックします。 sniff は、スコープマップ を使用して if 文の中のすべてのトークンを取得します。
忘却曲線を使ってこの知識を確実に記憶に残す
