phpcsのおさらい: コードのチェックと自動整形を使って快適なWordPressテーマ・プラグイン開発をしようその1

こんにちは、みみです。

今日はふんわりとした理解で使ってしまっているphpcsについて新年の心新たなタイミングでちょっとおさらいしておこうかなと思います。ええ、2021年初頭からノーコードブームに完全逆行しているのは認めます。まだもう暫くは人間がコード書かないと回らない部分もあるんですよ多分。

使っていますか、phpcs こと PHP CodeSniffer。PHP良くわかんない勢や初心者こそもっと使うべきツール、強い味方だと私は思っていまして、せっかくなのでそういう方にも良さが分かってもらえるように書いてみたいと思います。

ちゃんと使えるようになったら、えーこんな楽なの使ってたのズルくない？早く教えてよってなると思うの、多分きっとおそらく。がんばる。

phpcs – PHP CodeSniffer とは

PHP_CodeSnifferは、2つのPHPスクリプトのセットです。定義されたコーディング標準の違反を検出するためにPHP、JavaScript、およびCSSファイルをトークン化するメインのphpcsスクリプトと、コーディング標準の違反を自動的に修正するための2番目のphpcbfスクリプトがあります。PHP_CodeSnifferは、コードをクリーンで一貫性のある状態に保つために不可欠な開発ツールです。
squizlabs/PHP_CodeSniffer: PHP_CodeSniffer tokenizes PHP files and detects violations of a defined set of coding standards.

この記事を書こうと思った最終的なキッカケは、そもそも何だっけと思って「PHP CodeSniffer とは」でググったらぴったりくる日本語の説明文が見つからなかったことにあります（探し方が悪い説はある）。なので、取り敢えず公式らしい文を和訳してみました。

PHPもふんわり使っている勢なので理解が曖昧なのですが、つまりは PHPにおけるlinter（ソースコードを読み込んで内容を分析し、問題点を指摘してくれる静的解析ツール） だと言っても多分怒られないと思います。

このphpcsを使って、PHPのコード規約をちゃんと守ったコードに保ち、可読性や保守性を維持しましょう、というのが今回の趣旨です。リーダブルコードに近づく近道のひとつ、と言ってもいいのかもしれません。

（それの何が楽なのか、が分からない人はある意味幸せなのかも知れませんが、これからも短くてもちょっとでもコードを書く人で有るならば分かっていた方が幸せを保持することができ、もしかすると更に周囲に広げられるのではないかと。…ちょっと言い過ぎですね。）

PHPのコード規約とは

さてそもそもPHPのコード規約についてですが、これはQiitaに良いまとめがありましたので有り難く引用をば。PHPコーディング規約まとめ – Qiita

PHPを書くための様々なルールセットですね。沢山種類があります。其のうちの一つがこちら↓。なんですが多分WordPressがPHPだと認めて貰えていないのか入っていませんでしたｗ。

WordPressのPHPコード規約

PHP Coding Standards | Coding Standards Handbook | WordPress Developer Resources

何故いまだに array() で書かねばならんのか、とか度々物議をかましている気がするWordPressのPHPコード規約。でも、WordPressのお作法に習って書くにはナルホドなルールもちゃんと含まれています。

えー、いやいや、大事かも知れませんがそんな細かいルール全部、憶えてなんていられない。関数の名前どころか、ちょっとご無沙汰しているお知り合いのお名前さえ憶えられないポンコツ脳には無理難題です。が、そのチェックと自動整形を任せられるのがphpcsなのです。

phpcs の使い方

ここからは実際の使い方について説明していきます。Mac前提です悪しからず。（Windowsへの実装方法もググれば見つかるかと。Linuxとか使ってるガチ勢にはそもそもこの記事は必要ないはず。）

0. PHPがインストールされているか確認

そもそもPHPを書くためのツールなのでPHPが必要です。最近のMacだったら問題ないはずですが、ターミナル画面で $ php -v と打ってみてバージョンが返ってこなかったら、$ brew install php@7.4 とかでphpを入れましょう。（私の環境はまだ7.4.11ですが、今なら8系入れたくなりますね。ここをHomebrewとは?とかから全部説明したら別記事になるのでご容赦ください…一応PHPの公式ドキュメント貼っておきます PHP: macOS へのインストール – Manual）

1. phpcsをインストールするためにcomposerをインストールする

phpcs の使い方にはいくつか方法があるそうなのですが、私はcomposerでしか使ってないです。

composerって？

ここでComposerの説明をしておくべきかと思いますので手短に説明すると、

composerとはPHPのパッケージ管理システム
composerとは – Qiita

です。ここではphpcsを使うために必要なシステムだと思ってください。

2021/01/08 14:36 追記

composer、今はHomebrewでインストール出来るんだって！（岡本せんぱい、有難うございます！）

Mac使いは、これで大丈夫だよ！Homebrewほんと良いよね…

$ brew install composer

composer本体のインストールはこちらの記事などを参考にしてみてください。
Composerをインストールするなら公式ドキュメントを見よう! – Qiita
↑良記事です！読んでもらうとココで具体的な手順を解説しない訳も分かっていただけると思います。

Install Composer on Mac OS X – YouTube
英語だけど分かり良いかもと思った動画も貼っておきます。

…多分ココのハードルが一番高い気がするので、今度、動画とか撮れたら撮ってみようかなあ。でも需要ないかな…。

2. phpcsをcomposerに読み込ませる

さて、無事composerがインストールできたら、ターミナルに次のように入力して、phpcsパッケージをcomposerに読み込ませてあげます。グローバルで使う場合はこちら。

$ composer global require squizlabs/php_codesniffer

次に、phpcsのパスも通しておくと便利なので通しちゃいましょう。（zshの場合）

$ echo 'export PATH=$HOME/.composer/vendor/bin:$PATH' >> ~/.zshrc
$ source ~/.zshrc

ちゃんと設定できたか確認するためにバージョンを表示してみます。

$ phpcs --version

で PHP_CodeSniffer version 3.5.8 (stable) by Squiz (http://www.squiz.net) とか出力されたらOK。
これでPEARとか基本の規約は $ phpcs xxx.php でチェックが出来るようになります。

3. WordPressのPHPコード規約をphpcsに登録する

次に、WordPressのPHPコード規約を登録します。

gitでクローンして、

$ git clone -b master https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git ~/.composer/vendor/squizlabs/php_codesniffer/Standards/WordPress

--config-setオプションで設定します。

$ phpcs --config-set installed_paths ~/.composer/vendor/squizlabs/php_codesniffer/Standards/WordPress

WordPressのコード規約が追加されたかは、-i オプションで確認できます。

$ phpcs -i

これでコマンドラインで、phpcsを使ってWordPressのPHPコード規約のチェックと自動整形が出来るようになりました。

PHPを基本WordPressでしか書かないぞ、という方はdefault_standardをWordPressにしておくと良いかもです。
参照:https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options#setting-the-default-coding-standard

WordPressのコード規約ちょっと変わってるので他の規約とバッティングするんですよね。

$ phpcs --config-set default_standard WordPress

よしコレで、自動整形と規約チェックが出来るようになりました！
自動整形は phpcbf というコマンドで走ります。

$ phpcbf xxxx.php --report-summary --report-source

…が、コマンドラインで一々チェックするの面倒くさいですよね！

4. VS Code に設定して随時怒られておく

ということで、エディタで書いていると勝手にチェックしてくれるようにしましょう！

私のコードエディタはVisual Studio Code（VS Code）です。VS Code のお陰で長年のm■crosoftへの恨みつらみが解消されたといっても過言ではない素晴らしいエディタです。そう、PhpStormを使っているようなガチ勢にはこんな記事なんて必要ないのでコードに戻ってください。

かゆい処に手が届きまくる VS Code、当然のようにphpcsのプラグインがあります。

VS Codeへの phpcsの設定はこちらの公式ドキュメントが一次資料だと思います。
phpcs – Visual Studio Marketplace

VS Codeを開いて、拡張(extension)から phpcs を検索してインストールします。
ちょっとややこしいかも知れませんが、先にcomposerでインストールしたphpcsと、VS Codeのプラグインであるphpcsは別のモノです。

VS Codeをリスタートさせると、phpコードにphpcsが反映されるようになります。
規約のエラーがあれば、波線が表示され、マウスオーバーするとエラーの内容が表示されます。Shift + alt + Fで自動整形もしてくれますよ。やったね！

…でもこれだと確実にチェック出来ないし、気になった時だけとか気にする人だけしかチェックしなかったら意味がないし、なんか変数名でめっちゃ怒られるんだけど接頭詞なんぞ？とか、そもそもプロジェクト毎にチェックしたいルールが違うんだけど！とか、こんなわけわからん規約に従ってられるか！という方のためにAnnotated Rulesetがあります。そして、composer、GitHub Actions、Huskyという神ツールを使って楽をしましょう。ココからが本番。

が、結構長くなったので、入門編ということでいったんココまでにします。…その2を待ってくれる人は居るのだろうか。新年始めはデザイン関連の記事書こうと思ってたんだけどなあ…。

参考記事など:

phpcsの公式ドキュメントってサイトがないっぽくて、GitHubのWikiなんですよね。や、十分なんですけれど…なんか、さすが硬派っすって感じです。

Home · squizlabs/PHP_CodeSniffer Wiki

WordPressテーマレビュアー mirucon さんの記事が超参考になります。なんでそんなルールなん？て思ったら↓正式な書き方をまとめてみる、の記事を読むと良いかも。

その2はこちら！phpcsのおさらいその2: ルールセットの書き方、composerとGitHub Actions、Huskyの設定