MENU
Amazonで商品を見る セール会場へ

WordPress│Web制作でおすすめ！Visual Studio Codeの環境構築│phpcs phpcbf

広告
便利ツール・サービス

以下は過去のmacOS環境の設定記録です。現在の導入方法はWPCS公式READMEを確認してください。まずCLIで規約が読み込まれることを確認してからVS Codeへ連携します。信頼されていないワークスペースを自動で開く設定は不要です。

今までVisual Studio CodeでPHPを書いてた時は即効性の高いプラグイン（PHP Intelephense）で自動整形をしていたのですが、

Windows PCからMacBookAirに切り替えたのを機にWordPressのコーディング規約をチェックしてくれる定番のVisual Studio Codeの環境構築にしてみました。

WindowsでもPHPとComposerを用意すれば利用できます。以下のHomebrewとシェル設定はmacOS向けです。OSごとのパスや使用シェルに合わせて設定してください。

目次

著者

motokiのアバター motoki

WEB制作をしているデジタルノマド
WordPressのカスタマイズが好きで、色々と自作しています。

WordPressのカスタマイズに困ったらご相談ください！

MOTOKI合同会社
カスタマイズの依頼・相談

Web制作でおすすめのVisual Studio Codeの環境構築

以下の二つの拡張機能を導入します。

  • phpcs　→　コーディング規約を元にコードの状態を自動検知
  • phpcbf　→　コーディング規約通りにコードを自動整形

macOSの例ではHomebrewを用意します。OS共通で、CLIのPHPとComposer、およびWPCS公式READMEに記載されたPHP拡張が必要です。まずphp -vとcomposer --versionで使用する実行環境を確認してください。

Composerのインストール

brew install composer

完了したらcomposer -vで確認します。

CodeSnifferのインストール

composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require --dev wp-coding-standards/wpcs:"^3.0"

上のコマンドはWPCSと依存するPHPCSを導入し、規約登録用のComposerプラグインを許可します。既存のComposer設定を保存してから実行してください。導入後はcomposer global exec phpcs -- --versionで確認します。

続いて実際の実行ファイルの保存先を確認します。

composer global config bin-dir --absolute

表示されたディレクトリを必要に応じてPATHへ追加します。macOSでもBashとZshでは設定ファイルが異なるため、固定の.bash_profileへ一律に追記しません。以下のcomposer global exec形式なら、PHPCSのためのPATH追加を省略できます。

WordPressのコーディング規約の導入を確認

composer global show wp-coding-standards/wpcs

インストール先に依存しない形で登録済み規約を確認

composer global exec phpcs -- -i

上の一覧にWordPressがあれば、規約の登録を確認できます。検査時には--standard=WordPressを指定します。一覧に表示されることと、実際の検査でその規約を使うことは別です。

表示されない場合はComposerのインストール結果、規約登録プラグインの許可、実行しているPHPCSがグローバル導入先と一致するかを確認します。既存設定を消してやり直す前に原因を切り分けてください。

The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend, WordPress, WordPress-Core, WordPress-Docs and WordPress-Extra

次は対象ファイルを指定する例です。パスは自分のファイルへ変更してください。PHPCBFは修正可能な違反だけを直します。実行前にGitへ保存し、実行後は差分とPHPCSの再検査で残件を確認します。下の出力は過去の記録で、今回のコマンドを再実行した結果ではありません。

参考

composer global exec phpcs -- --standard=WordPress -s /Users/motoki/Documents/wordpress/themes/my-theme/index.php

結果

FILE: /Users/motoki/Documents/wordpress/themes/my-theme/index.php
---------------------------------------------------------------------------
FOUND 14 ERRORS AFFECTING 7 LINES
---------------------------------------------------------------------------
 1 | ERROR | [ ] Missing file doc comment
 3 | ERROR | [x] Tabs must be used to indent lines; spaces are not allowed
 3 | ERROR | [x] Opening PHP tag must be on a line by itself
 3 | ERROR | [x] No space after opening parenthesis is prohibited
 3 | ERROR | [x] No space before closing parenthesis is prohibited
 4 | ERROR | [x] Tabs must be used to indent lines; spaces are not allowed
 4 | ERROR | [x] No space after opening parenthesis is prohibited
 4 | ERROR | [x] No space before closing parenthesis is prohibited
 4 | ERROR | [x] Newline required after opening brace
 5 | ERROR | [x] Tabs must be used to indent lines; spaces are not allowed
 6 | ERROR | [x] Tabs must be used to indent lines; spaces are not allowed
 7 | ERROR | [x] Tabs must be used to indent lines; spaces are not allowed
 7 | ERROR | [x] Closing PHP tag must be on a line by itself
 9 | ERROR | [x] File must end with a newline character
---------------------------------------------------------------------------
PHPCBF CAN FIX THE 13 MARKED SNIFF VIOLATIONS AUTOMATICALLY
---------------------------------------------------------------------------
composer global exec phpcbf -- --standard=WordPress /Users/motoki/Documents/wordpress/themes/my-theme/index.php

結果

PHPCBF RESULT SUMMARY
------------------------------------------------------------------------------
FILE                                                          FIXED  REMAINING
------------------------------------------------------------------------------
/Users/motoki/Documents/wordpress/themes/suimin/index.php     13     1
------------------------------------------------------------------------------
A TOTAL OF 13 ERRORS WERE FIXED IN 1 FILE
------------------------------------------------------------------------------

ここで確認できれば、あとはVisual Studio Codeの設定と連携するだけです。

Visual Studio Codeの設定

2つの拡張機能をインストールします。

同じ名前で拡張機能を登録している人がいるので注意してください。

phpcbf　 制作者はPer Soderlind

phpcs　 制作者はIoannis Kappas　※過去に使用した拡張機能です。現在の保守状況と対応する設定名を確認して選んでください。

Visual Studio Codeで導入するphpcbfおよびphpcsの拡張機能一覧画面。

次に設定をします。

コマンドパレット（Windows/LinuxはCtrl+Shift+P、macOSはCommand+Shift+P）から設定JSONを開きます。

ショートカットキーで基本設定のコマンドパレットを開いた様子。

スクロールして settings.jsonで編集を開きます。

設定項目の中からsettings.jsonを開くメニューを選択する画面。

以下は当時の拡張機能向けの設定例です。既存のsettings.jsonを保存し、必要な項目だけを統合します。拡張機能によって設定名や整形の呼び出し方が異なるため、そのREADMEを確認してください。最初は自動保存整形を無効にして、手動実行の結果を確認します。

実行パスはユーザー名だけを置換せず、composer global config bin-dir --absoluteで調べたディレクトリ内のphpcs・phpcbfを指定してください。

{
  "editor.detectIndentation": false,
	"editor.insertSpaces": false,
	"editor.tabSize": 4,
	"files.eol": "\n",
	"phpcs.executablePath": "/Users/motoki/.composer/vendor/squizlabs/php_codesniffer/bin/phpcs",
	"phpcbf.executablePath": "/Users/motoki/.composer/vendor/squizlabs/php_codesniffer/bin/phpcbf",
	"phpcs.standard": "WordPress",
	"phpcbf.standard": "WordPress",
	"phpcbf.onsave": false,
	
	"editor.codeActionsOnSave": {
	},
}

参考

VS Code で phpcs と phpcbf を使ってWordPressのコーディングスタンダードで自動整形する | H.I. Art Work…

以下、解説です。

設定備考
editor.detectIndentationこの設定をfalseにすると、VS Codeはファイルを開くたびにインデント設定（スペースまたはタブ）を自動的に推測しようとはしなくなります。インデントスタイルが固定である場合や、異なるプロジェクト間で一貫性を保つために役立ちます。
editor.insertSpacesこの設定をfalseにすると、VS Codeはタブキーを押したときにスペースではなくタブを挿入します。
editor.tabSizeタブの表示幅を指定します。この例では4桁分です。editor.insertSpacesがfalseなので、タブキーで挿入するのはスペース4文字ではなくタブ文字です。
phpcs.executablePathPHP CodeSnifferの実行可能ファイルへのパスを指定します。PHP CodeSnifferは、PHPコードに対するコーディング規約の違反を検出するツールです。
phpcbf.executablePathPHP Code Beautifier and Fixerの実行可能ファイルへのパスを指定します。このツールは、コーディング規約に違反するコードを自動的に修正します。
phpcs.standardPHP CodeSnifferによって使用されるコーディング規約を指定します。この場合、WordPressのコーディング規約が使用されます。
phpcbf.standardPHP Code Beautifier and Fixerによって使用されるコーディング規約を指定します。この場合、WordPressのコーディング規約が使用されます。
phpcbf.onsave対応する拡張機能でtrueにすると保存時の修正を有効にします。この例のfalseでは無効です。手動実行と差分を確認してから必要に応じて切り替えます。
editor.codeActionsOnSave保存時に実行するコードアクションを指定します。この例の空オブジェクトではアクションを追加していません。

あとは実際のphpファイルを開き、ターミナルのウインドウの問題のところを確認しましょう。

解決するべきエラーが表示されています。

作業パスが写った旧「問題」タブの画像は掲載を取り下げました。確認する場所はVS Codeの「問題」タブです。

保存時にphpcbf（自動整形）が実行されない時

一度、コードを右クリックして手動でドキュメントをフォーマットしてみましょう。

手動整形に成功しても、保存時の実行が自動で設定されるとは限りません。選択した拡張機能の保存時設定、PHP用の既定フォーマッター、出力ログを確認し、別の整形拡張との競合を避けます。

コードを右クリックして手動でドキュメントのフォーマットを実行する操作画面。

phpcsのエラーコード解決集

よく検出されるエラーの解決方法の備忘録です。

Missing file doc commentエラー

ファイルの先頭にドキュメンテーションコメント（doc comment）を求められます。

解決方法としては、まずファイルの役割を記したdoc commentを追加します。例外的に抑制する場合だけ、実際の検出コードをphpcs -sで確認し、そのコードを指定します。以下は指定方法の例であり、Missing file doc commentを一律に解決するものではありません。

 // phpcs:ignore Generic.Commenting.DocComment.MissingShort

Using short ternaries is not allowedエラー

PHPの短縮形三項演算子 (?:) は、WordPressのコーディング規約では許可されていません。

完全な三項演算子 (? :) を使用するように変更します：

$voice_text = get_field( 'voice_text' ) ?: 'ここにテキストが入ります';

↓

$voice_text = get_field( 'voice_text' ) ? get_field( 'voice_text' ) : 'ここにテキストが入ります';

All output should be run through an escaping functionエラー

出力される全ての文字列は、セキュリティ上の理由からエスケープ処理を行う必要があります。

WordPressではこれを行うための関数がいくつか用意されています。

以下はHTMLの本文へ文字列を表示する例なのでesc_html()を使います。属性値はesc_attr()、URLはesc_url()、許可するHTMLを残す場合はwp_kses_post()など、出力先に合う関数を選びます。WordPress公式のエスケープ解説を参照してください。

<?php echo $voice_text; ?>

↓

<?php echo esc_html( $voice_text ); ?>

Found precision alignment of 2 spacesエラー

検出された行と検出コードを確認し、Gitへ保存したうえで対象ファイルにPHPCBFを実行します。ファイル全体のインデントを一律に削除する必要はありません。

差分を確認してPHPCSを再実行し、残った違反だけを規約に合わせて修正します。文字列やHTMLの空白まで変更していないかも確認してください。

まとめ

PCをmacに移行して、ちゃんとした環境構築ができたところで、

もっと早くやっておけばよかったと思いましたが、これでさらにより良いものが作れると思います。

気になった方は是非試してみてください。

あわせて読みたい
WordPress│wp-envの環境構築・使い方 Dockerを使うローカル開発環境の手順です。wp-env公式ドキュメントに沿って、Docker、Node.js、npm、Gitを用意します。既存のpackage.jsonを丸ごと置き換えず、必要なsc…

この記事で紹介しているコードは、GitHubのMOTOKI-LLC/WAZA-codeにもまとめています。

グローバル導入先はcomposer global config bin-dir --absoluteで調べ、その実際のパスを拡張機能へ指定します。~/.composerや~/wpcsが存在するとは限りません。phpcbfはファイルを書き換えるため、先にGitへ保存して対象ファイルだけへ実行し、差分を確認します。戻す場合はその差分だけを取り消してください。

よくある質問：Visual Studio CodeでWordPress向けにphpcs・phpcbfを設定するとき

この記事の環境構築は、今も使えますか？

記事では、以下は過去のmacOS環境の設定記録で、現在の導入方法はWPCS公式READMEを確認するよう案内しています。まずCLIで規約が読み込まれることを確認してからVS Codeへ連携します。

phpcsとphpcbfは、それぞれ何をしますか？

記事では、phpcsはコーディング規約を元にコードの状態を自動検知し、phpcbfはコーディング規約通りにコードを自動整形します。

導入するための前提条件は？

記事では、MacのHomebrewをインストールしている状態が前提条件です。Composer、CodeSnifferをインストールし、パスを登録して、WordPressのコーディング規約をインストールします。最後に登録済みの規約を確認して、WordPressという文字が確認できればOKです。

規約が確認できないときは、どうしますか？

Composerの導入結果、規約登録プラグインの許可、使用中のPHPCSの導入先を確認します。既存設定を消してやり直す前に切り分けます。

グローバルの導入先のパスは、どう調べますか？

記事では、導入先はcomposer global config bin-dir --absoluteで調べ、その実際のパスを拡張機能へ指定します。~/.composerや~/wpcsが存在するとは限りません。

phpcbfを使うときの注意点は？

記事では、phpcbfはファイルを書き換えるため、先にGitへ保存して対象ファイルだけへ実行し、差分を確認します。戻す場合は、その差分だけを取り消します。

エラーが出たときは、どう直しますか？

記事では、エラーコードごとに解決方法を紹介しています。たとえば、ファイル先頭のドキュメンテーションコメントを求められる場合は、ファイルの役割を記したdoc commentを追加します。短縮形三項演算子は許可されていないため、完全な三項演算子に変更します。出力される全ての文字列は、セキュリティ上の理由からエスケープ処理が必要です。

「Missing file doc comment」は、抑制して消してもよいですか？

例外的に抑制する場合だけにします。記事では、まずファイルの役割を記したdoc commentを追加します。抑制する場合は、実際の検出コードをphpcs -sで確認し、そのコードを指定します。記事の指定方法は例で、Missing file doc commentを一律に解決するものではありません。

便利ツール・サービス
  • URLをコピーしました！

制作・運用のご依頼はこちら

MOTOKI合同会社のサービス

WordPressの制作・カスタマイズ・高速化・SEO対策・保守まで、Webサイトに関する業務を一括で承ります。料金はサービスごとに公開しています。

サービス一覧を見る
無料で相談する

WAZAの有料記事のサブスクリプションも開始しました。

あわせて読みたい
アフィリエイト付き！有料記事のサブスクリプションについて WAZAでは特に有益な記事は有料記事とさせていただいてます。 本記事では有料記事をリストでまとめました。 有料記事の購読プランと、対象コンテンツを紹介できるアフィ...

関連記事

目次