PHPプロジェクトに CS FIXERを導入してコード整形を自動化する

php cs-fixer をPHPプロジェクトに導入して、コード整形を自動化する手法を紹介します。

CS FIXER によるコード整形

コード整形は、複数人での開発作業を円滑に進める上で非常に重要な問題です。

インデントの置き方や、ブラケット { } の記述位置などは、コード実行上大きな問題となるケースは少ないですが、
複数人開発での作業で、コードの書き方が統一できていないと、バージョン管理上で不必要な差分が生じたり、
それぞれのコードを相互に確認し合う上での可読性が下がったりと、生産性に大きな影響を及ぼすケースがあります。

コード整形は、通常何かしらの「コード規約」にもとづいて正しいコードの書き方を定義した上で行われます。
コード規約はチーム内で個別に持つケースもありますが、一般的には PSR-0 や PSR-2 などの PHP 界隈で共通の標準規約を用いるケースがほとんどです。チーム個別のコード規約は、制作・保守にコストがかかるだけでなく、新規参入したメンバーにとっての学習負担が大きい面も無視できないため、出来るだけ標準的なコード規約を採用する方が良いでしょう。

PSR-0 原文 日本語訳

PSR-2 原文 日本語訳

採用すべきコード規約が固まったとしても、それを目視で各自が遵守していくと言うのは非常に苦痛な作業です。
コードチェックを自動で実行してくれるツールは各種存在しますが、できればコードの整形まで自動で行ってもらえるほうが負担は少なくて済みます。

php cs-fixer は、ルールに基づいたコードの整形を自動で実行してくれるツールとして幅広く使われている整形ツールです。
標準で PSR-0 / PSR-2 のコード整形に対応するため、様々な現場で導入することが出来ます。

導入

以下のコマンドで cs-fixer をインストールします。

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

コードの修正 を行う場合 fix コマンドを指定します。例えば app フォルダ内のファイルを再帰的にチェックする場合、以下のようなコマンドになります。

$ vendor/bin/php-cs-fixer fix app 

実行後自動的に指定されたフォルダ内のコードが修正されます。

構文修正の必要があったかどうかを問わず、終了コードは 0 です。

cs-fixer は、構文エラーなどのあるファイルを適切に取り扱うことが出来ず、エラーを報告しますが、この場合でも fix コマンドの終了コードは 0 となります。

単純にコードのチェックのみを実施したい場合には、 --dry-run オプションを利用します。

$ vendor/bin/php-cs-fixer fix app --dry-run

--dry-run オプションを利用する場合、修正スべき内容がない場合のみ終了コードが0となります。

修正すべき内容がある場合エラーコード 8 、構文エラーで修正リストが出せない場合は 4 のエラーコードが返ってきます。

コード整形と運用

コマンドを実行してコードの整形を行うことが出来るようになりました。

一旦、コード整形を実行すると .php_cs.cache という名前のファイルが生成されます。これは次回からのコードチェックを高速に実行するために必要なファイルですので、.gitignore に追加するなどしてバージョン管理から除外し、ローカルでのみ保管しておきましょう。

コマンドを実行すると自動で整形してくれるものの、コード編集の度にコマンドを実行するのもなかなか面倒なものです。

Git の commit hook などを利用してCommit 前の自動実行を行うのも一つの手ですが、ここは PhpStorm を利用したコード整形の自動実行に挑戦してみましょう。

PhpStorm の設定

cmd + , の設定画面から Tools > External Tools を選択します。

+ のアイコンから設定を追加し、 Name に cs-fixer などと記述し、以下のように設定します。

  • Program $ProjectFileDir$/vendor/bin/php-cs-fixer
  • Parameters fix $FilePath$
  • Working dir $ProjectFileDir$

これでファイル編集中の右クリックメニュー External Tools 内に cs-fixer が追加され、クリックする事で編集中のファイルに コード整形を適用できるようになりました。

CI によるコードチェックの自動実行

Githook を利用するにせよ、PhpStorm の連携を利用するにせよ、複数人のプロジェクトメンバーでコードの運用を実施する場合、必ずCI によるコード規約のチェックを実行しましょう。

それぞれ異なる環境でコードチェックを実施する場合、コードチェックの漏れは必ず何処かで生じるでしょう。それを阻止してくれるのがCI上でのコードチェックです。

CI 上では --dry-run によるコードチェックのみを行い、コードの整形自体はコミッターの手で行うのがよいでしょう。

カテゴリー: PHP

PHPプロジェクトに CS FIXERを導入してコード整形を自動化する」への1件のフィードバック

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です