PHP_CodeSniffer の使い方

NEW
2021/09/05

プログラムを書いていると気になるのがコードの読みやすさです。 複数人で開発している場合などは特にコードの読みやすさは重要です。

PHP_CodeSniffer とは?

PHP_CodeSniffer は、PHPのコードがちゃんとコーディング規約に沿って記述されているか検査したり、 コーディング規約に違反している個所を自動的に修正してくれるツールです。 コードをクリーンで一貫性のある状態に保つために役に立ちます。

phpcs と phpcbf コマンド

PHP_CodeSniffer は、2つのコマンドで構成されています。

phpcs コマンド

1つ目のコマンドは、phpcs コマンドです。PHP のコードを検査し、コーディング規約に違反している個所を検出してくれます。 phpcs というコマンド名は、"PHP Code Sniffer" の略です。こちらのコマンドがメインとなります。

phpcbf コマンド

2つ目のコマンドは phpcbf コマンドです。コーディング規約に違反している個所を、自動的に正しいコードに修正してくれます。 phpcbf というコマンド名は、"PHP Code Beautifier and Fixer" の略です。

コーディング規約に違反している個所を手動で1つ1つ直していくことも可能ではありますが、コードが大量にある場合は作業量が膨大になってしまい、現実的ではありません。 自動的に修正できる箇所は、自動的に修正した方が効率的です。 但し、違反している個所の全てをこの phpcbf コマンドで修正できるわけではありません。 あくまで自動的に修正できる箇所のみです。 それ以外の個所は手動で修正する必要があります。

PHP_CodeSniffer のインストール

さっそくですがインストールしていきましょう。

Composer でインストールする

PHP_CodeSniffer をインストールする方法はいろいろありますが、Composer を使っている場合は Composer を使ってインストールするのが楽だと思います。 Composer を使って PHP_CodeSniffer をインストールするには、下記のコマンドを実行するだけです。 基本的には開発環境で使うツールだと思うので、--dev オプションを付けておきましょう。 Composer の使い方がわからないという方は、まずは「Composer 再入門」を参考にしてください。

php composer.phar require --dev "squizlabs/php_codesniffer"

インストールできたか確認する

PHP_CodeSniffer をインストールすると、2つのコマンド phpcs コマンドと phpcbf コマンドが使えるようになっていますので、それぞれのコマンドが使用できるか確認してみましょう。 実行ファイルは ".\vendor\bin\" ディレクトリにあります。

phpcs コマンドが使えるか確認する
.\vendor\bin\phpcs -h
phpcbf コマンドが使えるか確認する
.\vendor\bin\phpcbf -h

基本的な使い方

インストールできたので、さっそく使ってみます。 phpcs コマンドも phpcbf コマンドも使い方はほとんど同じなので、以降 phpcs コマンドを使って説明します。

単一のファイルを検査する

1つのファイルを検査する場合は、検査したいファイル名を指定します。 検査したいファイル名はスペース区切りで複数指定できます。

".\src\hoge.php" ファイルを検査する場合
.\vendor\bin\phpcs .\src\hoge.php
".\src\hoge.php" ファイルと ".\src\fuga.php" を検査する場合
.\vendor\bin\phpcs .\src\hoge.php .\src\fuga.php

複数のファイルを検査する

複数のファイルを検査する場合は、検査したいディレクトリ名を指定します。 検査したいディレクトリ名はスペース区切りで複数指定できます。

".\src" ディレクトリを検査する場合
.\vendor\bin\phpcs .\src
.\src ディレクトリと .\tests ディレクトリを検査する場合
.\vendor\bin\phpcs .\src .\tests

WARNING を非表示にする

PHP_CodeSniffer を実行した際に表示される指摘点には、その内容によって ERROR と WARNING の2種類があります。 指摘点が大量に出る場合など、ERROR だけを表示して、WARNING を非表示にしたい場合もあると思います。 その場合は、-n オプションを付けます。

.\vendor\bin\phpcs -n .\src

出力内容に色を付ける

デフォルトでは出力内容には色が付いていないので白黒な画面になってしまうと思われますが、この出力内容に色を付けることができます。 色が付いていると ERROR や WARNING などが発生した場合にわかりやすくなります。 色を付けるには --colors オプションを付けます。

.\vendor\bin\phpcs --colors .\src
出力内容
   2 | ERROR   | [ ] Missing file doc comment
   4 | WARNING | [ ] Line exceeds 85 characters; contains 95
     |         |     characters

進捗状況を表示する

大量のファイルがある場合などでは、進捗状況が表示されていた方が便利かもしれません。 その場合は、-p オプションを付けます。 -p オプションを付けるとコマンドの出力の最初に実行結果が表示されます。

.\vendor\bin\phpcs -p .\src
出力内容
E.E.EEWEE.EEWEEEEE.EEEEESEEEEEEEEEEE......EEEEEEEEEEEEEEE..E 60 / 76 (79%)
........E.......                                             76 / 76 (100%)

E は ERROR、W は WARNING、S は SKIP の意味です。

コーディング規約を変更する

PHP_CodeSniffer で使用されるデフォルトのコーディング規約は、PEARコーディング標準になっています。 しかし、これだと困る人も多いと思います。

使用できるコーディング規約の一覧を表示する

PHP_CodeSniffer で使用できるコーディング規約の一覧を表示するには -i オプションを使用します。

.\vendor\bin\phpcs -i
出力内容
The installed coding standards are MySource, PEAR, PSR1, PSR12, PSR2, Squiz and Zend

コーディング規約を変更する

コーディング規約を変更する場合は、--standard オプションを使用します。

コーディング規約を PSR-12 に変更する場合
.\vendor\bin\phpcs --standard=PSR12 .\src

独自のコーディング規約を使用する

PHP_CodeSniffer にはいくつかのコーディング規約が標準でインストールされていますが、それらでは事足らず、独自のコーディング規約が使用したいと思うこともあると思います。 例えば、お仕事で開発をしている場合、会社やプロジェクト毎に独自のコーディング規約があったりするものです。 PHP_CodeSniffer では、使用するコーディング規約に関する細かな設定を ruleset.xml というXMLファイルにて指定することができます。

ruleset.xml を使用する

ruleset.xml を使用する方法は2つあります。

--standard オプションで指定する

ruleset.xml を使用する方法の1つ目は、--standard オプションで使用したいファイルを指定することです。 複数のファイルを使用して、設定を切り替えたい場合などには便利かもしれません。

.\vendor\bin\phpcs --standard=.\custom_ruleset.xml .\src

デフォルトの設定ファイルを使用する

もう1つの方法は --standard オプションは指定せず、デフォルトの設定ファイルを使用する方法です。

--standard オプションを指定しない場合(つまりデフォルト)、 PHP_CodeSniffer は現在のディレクトリから親ディレクトリの方向に向かって ruleset.xml ファイルを探しに行きます。 この時に探されるファイルの名前は、「.phpcs.xml」「phpcs.xml」「.phpcs.xml.dist」「phpcs.xml.dist」の4つです。 この4つのファイル名のどれかと一致するファイルが見つかった場合に、そのファイルが自動的に読み込まれます。 もし複数のファイルが見つかった場合は、前述の順番で優先的に読み込まれます。

ruleset.xml のフォーマット

ruleset.xml は拡張子を見ればわかるとおりXMLファイルです。 ruleset タグをルートとし、その中に設定内容のタグを記述していきます。 rule タグの ref 属性で使うルールの名前を指定し、そのタグの中にそのルールの設定を記述していく感じです。 XMLなのでコメントも書けます。

どんなルールがあるか、どんな設定が使えるかは、ここでは記載しません。 あまりにも大量にありますので、英語ですが公式のドキュメントを見てもらった方が良いと思います。

ちなみにですが、公式のドキュメントに全てのルールが書かれているわけではないので注意してください。 もし全て知りたければ、PHP_CodeSniffer のソースコードを見てください。

ここでは簡単な例だけ記載しておきます。

phpcs.xml
<?xml version="1.0"?>
<ruleset name="CustomStandard">

	<!-- PSR-12のルールを全て適用 -->
	<rule ref="PSR12">

		<!-- 但し、タブでのインデントを禁止するルールは適用しない -->
		<!-- ※ つまり、タブでのインデントを許可する -->
		<exclude name="Generic.WhiteSpace.DisallowTabIndent"/>

	</rule>

	<!-- 1行の文字数が120文字以上で警告、160文字以上でエラー -->
	<rule ref="Generic.Files.LineLength">
		<properties>
			<property name="lineLimit" value="120" />
			<property name="absoluteLineLimit" value="160" />
		</properties>
	</rule>

</ruleset>

違反したルールの名前を表示する

phpcs コマンドに、-s オプションを付けると、メッセージの後に違反したルールの名前を表示してくれます。 どのルールが動作したのかが確認しやすくなりますので、独自のコーディング規約を使用する際には便利でしょう。

.\vendor\bin\phpcs -s .\src
出力内容
  4 | ERROR | [x] Header blocks must be separated by a single blank
    |       |     line (PSR12.Files.FileHeader.SpacingAfterBlock)
 26 | ERROR | [x] Blank line found at start of control structure
    |       |     (Squiz.WhiteSpace.ControlStructureSpacing.SpacingAfterOpen)

Composer スクリプトとして登録する

複数のディレクトリをまとめてチェックしたい場合など、ディレクトリ名や、各種オプションを毎回入力するのは面倒に感じてくると思います。 特に、ここまでの説明で散々繰り返し記載してきた ".\vendor\bin" を記述するのが面倒に感じていると思います。 そこで、Composer スクリプトとして登録しておくと、入力の手間が少なくなって便利です。 Composer スクリプトでは、 ".\vendor\bin" に PATH が通っているので、".\vendor\bin" を入力する必要はありません。 Composer スクリプトの使い方がわからないという方は、「Composer 再入門(その2:スクリプト)」を参考にしてください。

composer.json
{
	"name": "hoge/hoge",
	"require-dev": {
		"squizlabs/php_codesniffer": "^3.6"
	},
	"scripts": {
		"cs-check": "phpcs --colors -p ./src ./tests",
		"cs-fix": "phpcbf --colors -p ./src ./tests"
	}
}
登録したスクリプト cs-check を実行する
php composer.phar cs-check
登録したスクリプト cs-fix を実行する
php composer.phar cs-fix

参考サイト

関連記事

PHPのコードを実行する前に、バグがあるかどうか調べられると便利だとは思いませんか?PHPはスクリプト言語ですので、いくら文法的に正しいコードであっても、実際に実行させるまでバグか発生するかどうかわからないという、スクリプト言語であるが故の本質的な問題を抱えています。C や Java など他のコンパイル言語ではコンパイル時にエラーになるようなコードであっても ...
PHP_CodeSniffer や PHPStan などで、コードの文法的な正しさは確認できますが、そのコードが本当に正しい動作を行っているかどうかを確認するためには、やはり最終的には動作させてみるしかありません。PHPUnit とは?PHPUnit は、PHPのテストフレームワークです。その名前からわかる通り、基本的には単体テスト(UnitTest)に使用 ...
PHPでの開発効率を向上させるために、PHP自体に機能を追加するという方法があります。Xdebug とは?Xdebug は、PHPでの開発効率を向上させるためのさまざまな機能を提供してくれるPHPの拡張機能(エクステンション)です。Xdebug でできることは下記の6つです。ステップ実行:スクリプトの実行中にIDEまたはエディターでコードをステップ実行開発ヘ ...
もはやPHPで開発を行う際に、使用していないプロジェクトは探すのが大変なぐらいスタンダードな存在となった Composer ですが、昨年めでたく 2.0 になったということで、改めて少しまとめてみます。今更とか言っちゃダメです。Composer とは?Composer は、PHPの依存関係管理のためのツールです。世界中のエンジニアが作成してくれたライブラリ( ...

記事検索

最新記事

RSSフィード