PHP CodeSnifferの導入方法

Laravel は、コーディング規約として PSR-2 を推奨しています。

Contribution Guide

https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md

まぁいろいろ細々書いてあるんですよね。

• インデントは 4 文字
• 1 行は 80 文字以下
• namespace 宣言の後は必ず１行の空白行を設けよ
• クラスの開始中括弧は次の行に移動させる
• メソッドの開始中括弧は次の行に移動させる
• PHP ファイルは、LF 改行にする
• PHP ファイルは、1 行の空白行で終了させる(これ以外とできていないファイル多い...)

それらを守ったファイル例が下記です。

<?php
namespace Vendor\Package;

use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class Foo extends Bar implements FooInterface
{
    public function sampleMethod($a, $b = null)
    {
        if ($a === $b) {
            bar();
        } elseif ($a > $b) {
            $foo->bar($arg1);
        } else {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static function bar()
    {
        // method body
    }
}

正直{}とかの位置に関しては、下記の場合自動整形して欲しいですよね。

    final public static function bar(){
        // method body
    }

そこで今回は、PSR-2 のコーディング規約に従ったコーディングを実施するため、VSCode にコーディング規約をチェックする拡張機能の導入方法を明記します。

PHP_CodeSniffer によるチェックは、パッケージでも可能だが、今回は VSCode の拡張機能でも準備されているため、そちらを使うことにしています。

PHP CodeSniffer とは

PHP_CodeSniffer は、2 つの PHP スクリプトがセットになっています。

• 定義されたコーディング標準の違反を検出するための phpcs スクリプト
• コーディング標準の違反を自動的に修正するための phpcbf スクリプト

コードチェックツールとしては、「phpcs」と「php cs fixer」が有名。

• phpcs⇨ コーディング規約のチェックツール
• php cs fixer⇨ コーディング規約に則った自動整形までしてくれるツール

とのことで、今回は「php cs fixer」を導入します。

今回のコードチェックは拡張機能で実施できます。

しかし、拡張機能を使うため本体に「php cs fixer」をインストールする必要があります。

php cs fixer(Laravel 側)導入方法

composer コマンドで php-cs-fixer をインストールします。

composer require --dev friendsofphp/php-cs-fixer

composer.json にすでに登録されている場合は下記コマンドだけで OK です。

composer install

その後、正常にインストールされたかを確認するため、下記コマンドを叩き、バージョンが表示されるかを確認しましょう。

$ ./vendor/bin/php-cs-fixer --version
PHP CS Fixer 3.0.0 Constitution by Fabien Potencier and Dariusz Ruminski

整形設定ファイルの作成

php-cs-fixer は、細々な設定しなくてもよしなに整形してくれるものの、整形方法を細かくカスタマイズも可能です。

整形設定をお好みのものにするには、まず.php_cs.distと言う名前で整形ルール設定ファイルを作成します。

※.php_cs.dist と.php_cs の 2 つのファイルが有ると、.php_cs が優先して読み込まれます。

.php_cs.dist はチーム共有のもの、.php_cs は開発者個人のものという位置づけで使うこともできます。

(.php_cs は.gitignore で Git へコミットされないようにしておきましょう)

下記が設定ファイルとなります。

<?php declare(strict_types=1);

$finder = PhpCsFixer\Finder::create()
    ->in([
        __DIR__ . '/app',
        __DIR__ . '/config',
        __DIR__ . '/database/factories',
        __DIR__ . '/database/seeds',
        __DIR__ . '/routes',
        __DIR__ . '/tests',
    ]);

$config = new PhpCsFixer\Config();

return $config
    ->setRiskyAllowed(true)
    ->setRules([
				'@PSR2' => true,
        'blank_line_after_opening_tag' => false,
        'linebreak_after_opening_tag' => false,
        'declare_strict_types' => false,
        'phpdoc_types_order' => [
            'null_adjustment' => 'always_last',
            'sort_algorithm' => 'none',
        ],
        'no_superfluous_phpdoc_tags' => false,
        'global_namespace_import' => [
            'import_classes' => true,
            'import_constants' => true,
            'import_functions' => true,
        ],
        'php_unit_test_case_static_method_calls' => [
            'call_type' => 'this'
        ],
        'phpdoc_align' => [
            'align' => 'left',
        ],
        'not_operator_with_successor_space' => true,
    ])
    ->setFinder($finder);

※'@PSR2' => trueですが、代わりに'@PhpCsFixer:risky' => trueとしている文献もあります。

ただ、PhpCsFixer:riskyは php のバージョン 8 では動かないので注意です。

設定ファイルに関しては、下記ツールを使うと、お好みで設定とかも可能です。

加えたいルールプリセットやルールを選んでいくと設定ファイルを書き出してくれます。

PHP-CS-Fixer Configurator

また、コード整形すると、.php-cs-fixer.cacheというファイルが作成されます。

このファイルは Git 管理外としておきたいので、.gitignoreに追加しておきましょう。

.php-cs-fixer.cache

整形実行

php-cs-fixer の準備はできたので、ここからは実際に整形をしていきます。

PHP_CodeSniffier によるチェック ⇨ 整形はしていないのでエラーが出るはずです。

./vendor/bin/phpcs --report=summary .

下記コマンドで、整形されるファイル内容が確認できます。(この時点では dry run のため実際に整形修正されていません)

# dry run
$ ./vendor/bin/php-cs-fixer fix -v --diff --dry-run

実際に整形実行する際は、オプションである--dry-run を入れずにコマンド実行しましょう。

# fix
$ ./vendor/bin/php-cs-fixer fix -v --diff

再度 PHP_CodeSniffier によるチェックでエラーが出ないことを確認しましょう。

./vendor/bin/phpcs --report=summary .

拡張機能の導入方法

Laravel 側の導入は終わったので、今度は VSCode に導入します。

インストール

VSCode の拡張機能インストール画面で、[php cs fixer]で検索し、下記キャプチャの php cs fixer(0.2.2)をインストールする。

settings.json 修正

PHP CS Fixer のプラグインをインストールしたら、設定ファイルである settings.json の修正します。

以下のコマンド等を実行して、settings.json を開きます。

command + shift + p

settings.json に、以下の項目を追記します。

保存時、整形するようにします。

パスに関しては、先ほど composer で php-cs-fixer をインストールしているので、bin/配下に php-cs-fixer があるはずなので、そちらを参照するようにします。

{
	"php-cs-fixer.onsave": true, // 保存時に整形を実行
	"php-cs-fixer.executablePath": "[プロジェクト名]/vendor/bin/php-cs-fixer", // php-cs-fixerのパス
}

動作確認

VSCode で編集し、保存後コードが自動整形してくれるかを確認しましょう。

public function aaa() {
            echo "Hello";
    }
↓
public function aaa()
{
    echo "Hello";
}

参考記事

http://www.infiniteloop.co.jp/docs/psr/psr-2-coding-style-guide.html