July 1, 2021 • ☕️☕️ 8 min read
PHP_CodeSniffer(PHPCS) というツールで、書いたコードがコーディング規約に準拠しているかをコマンド1発で確認できるようになる。
コマンドは「phpcs」。
以下、フレームワークは Laravel を使ってます。
https://github.com/squizlabs/PHP_CodeSniffer
phpcs と phpcbf の2種類のツールがある。
公式の説明資料は、これ。
composer global require "squizlabs/php_codesniffer=*"
グローバルインストールする必要は無いのでは? あと、本番で使う必要は無いので、「—dev」オプションを付けた方がいいと思う。
なので、自分が使用したコマンドは以下。
composer require --dev "squizlabs/php_codesniffer=*"
composer remove squizlabs/php_codesniffer
./vendor/bin/phpcs --version
./vendor/bin/phpcs -h
./vendor/bin/phpcbf -h
最小構成
phpcs [ファイル名 orディレクトリ名]
よく使うオプションを付けると、こんな感じ
phpcs --report=source --standard=PSR2 [ファイル名 orディレクトリ名]
./vendor/bin/phpcs app/Repositories/PlaylistRepository.php
./vendor/bin/phpcs --report=source --standard=PSR2 app/Repositories/PlaylistRepository.php
./vendor/bin/phpcbf --report=summary --standard=/MyStandard/phpcs.xml app/Repositories/PlaylistRepository.php
root@ddfa20fadae0:/var/www/html/my-laravel-app# ./vendor/bin/phpcs --report=source --standard=PSR2 app/Repositories/PlaylistRepository.php
PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
------------------------------------------------------------------------
STANDARD CATEGORY SNIFF COUNT
------------------------------------------------------------------------
Squiz Classes Valid class name not camel caps 1
------------------------------------------------------------------------
A TOTAL OF 1 SNIFF VIOLATION WERE FOUND IN 1 SOURCE
------------------------------------------------------------------------
Time: 1.26 secs; Memory: 8MB
以下から選択可。
詳細はヘルプコマンドを参照。
エラーの詳細を調べる場合、—report=full が情報量が多くておススメ。
通常の使用は、「xml」「json」といった形式に出力とか。
あとは、「source」「summary」等がダイジェストで確認できていい感じ。
以下、オプションの解説。
「PSR2」等のコーディング規約を指定する方法と、コーディング規約ファイルを指定する方法の2通りがある。
./vendor/bin/phpcs --report=source --standard=PSR2 app/Repositories/PlaylistRepository.php
使用可能なコーディング一覧は、以下のコマンドで確認可。
./vendor/bin/phpcs -i
//=> The installed coding standards are MySource, PEAR, PSR1, PSR12, PSR2, Squiz and Zend
./vendor/bin/phpcbf --report=summary --standard=phpcs.xml app/Repositories/PlaylistRepository.php
コーディング規約の PSR2 をベースに記述した場合の phpcs.xml の記述例が以下。(公式)
https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Standards/PSR2/ruleset.xml
上記のではファイル名が「ruleset.xml」となっているが、ファイル名は「phpcs.xml」という名前にするのがおススメ。
理由は後述。
ノンカスタマイズの PSR2 を使う場合の最小構成は、こんな感じ。
<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="PSR2" xsi:noNamespaceSchemaLocation="../../../phpcs.xsd">
<description>The PSR-2 coding standard.</description>
<arg name="tab-width" value="4"/>
<rule ref="PSR2"/>
</ruleset>
「PEAR」が適用される。
コーディング規約を暗黙にしておくのは避けたいので、しっかりと明示しておく方がよさそう。
ちなみに、—standard オプションを指定しなかった場合でも、「phpcs.xml」というファイルが存在していれば、それをコーディング規約定義ファイルとして読み込んでくれる。
「どういう事だ?」と思って調べてみたら、「.phpcs.xml」「phpcs.xml」「.phpcs.xml.dist」「phpcs.xml.dist」というファイルが存在していた場合、「—standard=phpcs.xml 」とファイル名を指定しなくても、暗黙的にそれらを定義ファイルとして読み込んでくれるみたい。
https://github.com/squizlabs/PHP_CodeSniffer/blob/master/src/Config.php#L348
$defaultFiles = [
'.phpcs.xml',
'phpcs.xml',
'.phpcs.xml.dist',
'phpcs.xml.dist',
];
適用の優先順位は
.phpcs.xml > phpcs.xml > .phpcs.xml.dist > phpcs.xml.dist
の順番。
適用されるファイルは1つだけ。(.phpcs.xml と phpcs.xml が存在していた場合、適用されるのは .phpcs.xml のルールのみ)
混乱の原因になるので、ファイルは1つだけにしておく。
次回、定義ファイルの詳細について書く予定。
PHP のコーディング規約は、PSR がメジャーですが、「PSR2」と言った場合、PSR0~1 も内包するので、ルールの詳細を把握するのが結構面倒だったりする。
(普段は整形ツールにお任せしている派)
以下のサイトが、体系的にまとめられていて分かりやすかった。
PHPのコーディング規約まとめ。PSR-2, CakePHP, Symfony, WordPress, FuelPHPなどの5つの規約の概要と特徴的なルール