2026年6月16日

PHPのコード品質管理ツール（PHPStan等）の導入：WordPressのテーマ・プラグインに静的解析と規約チェックを組み込む

Webサーバー・Apache

PHP のコード品質を保つには、型や呼び出しの誤りを見つける PHPStan、書き方の規約とセキュリティ上の書き漏れを見つける PHP_CodeSniffer（WordPress Coding Standards）、PHP の新しいバージョンで動くかを確かめる PHPCompatibility を組み合わせ、Composer のスクリプトと CI で毎回自動実行する形が扱いやすい構成です。この記事では、WordPress のテーマやプラグインを例に、それぞれのツールの役割、Composer での導入と設定ファイル、既存コードの大量の指摘への向き合い方、GitHub Actions での自動実行までを説明します。個々のツールを深く掘り下げるのではなく、複数のツールを1つの流れにまとめることを目的にしています。

ツールごとの役割

似た名前のツールが多いので、まず「何を見つけるか」で整理します。

PHPStan: コードを実行せずに読み、存在しないメソッドの呼び出し、型の食い違い、null になりうる値の扱い漏れなどを見つけます。レベルを上げるほど厳しくなります。
PHP_CodeSniffer（phpcs）と WordPress Coding Standards（WPCS）: インデントや命名などの書き方に加えて、出力時のエスケープ漏れ、nonce の検証漏れ、$wpdb の準備されていないクエリなど、WordPress 固有の注意点を指摘します。付属の phpcbf で自動修正できる指摘もあります。
PHPCompatibility（WordPress 向けは PHPCompatibilityWP）: 指定した PHP のバージョンで削除・変更された関数や構文を使っていないかを調べます。サーバーの PHP を上げる前の確認に役立ちます。
Rector: 指摘するだけでなく、古い書き方を新しい書き方へ自動で書き換えるツールです。PHP のバージョンアップに伴う大量の修正に向きますが、変更が大きいため、ほかのツールが落ち着いてから使うのが順番として無理がありません。

PHPStan と phpcs は見ている観点が違うため、どちらか一方で足りるものではありません。PHPStan は「このコードは動くか」、phpcs と WPCS は「WordPress のやり方に沿って安全に書かれているか」を見ると考えると分かりやすくなります。

Composerで開発用にまとめて入れる

ツールはプロジェクトごとに開発用の依存関係（require-dev）として入れます。チームの全員と CI が同じバージョンを使えるようになり、composer.lock でバージョンが固定されます。

composer require --dev phpstan/phpstan szepeviktor/phpstan-wordpress phpstan/extension-installer
composer require --dev wp-coding-standards/wpcs phpcompatibility/phpcompatibility-wp \
  dealerdirect/phpcodesniffer-composer-installer

szepeviktor/phpstan-wordpress は、PHPStan に WordPress の関数やフックの情報を教える拡張です。これがないと、add_action() や get_option() が「存在しない関数」として大量に指摘されます。phpstan/extension-installer と dealerdirect/phpcodesniffer-composer-installer は、拡張や規約を自動で登録する Composer プラグインです。Composer 2.2 以降では、プラグインの実行を composer.json で許可する必要があります。

{
  "config": {
    "allow-plugins": {
      "phpstan/extension-installer": true,
      "dealerdirect/phpcodesniffer-composer-installer": true
    }
  },
  "scripts": {
    "lint": "phpcs",
    "lint:fix": "phpcbf",
    "analyse": "phpstan analyse --memory-limit=1G",
    "check": ["@lint", "@analyse"]
  }
}

scripts に登録しておくと、composer check の1コマンドで両方を実行できます。ツールの細かいオプションを覚えていなくても、同じ手順で確認できることが大きな利点です。

インストールのあと、vendor/bin/phpcs -i を実行して、WordPress や PHPCompatibilityWP が登録済みの規約の一覧に表示されるかを確認します。表示されない場合は、allow-plugins の許可が抜けていることが多い原因です。

PHPStanの設定

プロジェクトの直下に phpstan.neon.dist を作ります。.dist 付きのファイルを Git に含め、個人ごとの上書きは .dist なしの phpstan.neon で行う、という使い分けがよく使われます。

includes:
    - phpstan-baseline.neon

parameters:
    level: 5
    paths:
        - my-plugin.php
        - includes/

paths には自分で書いたコードだけを指定します。vendor を含めると解析に時間がかかり、直せない指摘が大量に出ます。

最初から最高レベルにすると、既存のコードでは指摘が多すぎて手が付けられません。まずは低いレベルで指摘がなくなるまで直し、少しずつ上げます。WordPress のコードは配列や mixed 型の値を多く扱うため、中程度のレベルから先は、PHPDoc で型を補う作業が中心になります。

includes に書いた phpstan-baseline.neon は、次の節で作るファイルです。まだ作っていない段階では、その2行を外してから実行してください。

WordPress Coding Standardsの設定

phpcs の設定は、プロジェクト直下の .phpcs.xml.dist に書きます。ファイル名の候補はいくつかありますが、この名前なら phpcs を引数なしで実行したときに自動で読み込まれます。

<?xml version="1.0"?>
<ruleset name="My Plugin">
  <description>My Plugin の規約</description>

  <file>.</file>
  <exclude-pattern>/vendor/*</exclude-pattern>
  <exclude-pattern>/node_modules/*</exclude-pattern>
  <exclude-pattern>/build/*</exclude-pattern>

  <arg name="extensions" value="php"/>
  <arg name="parallel" value="8"/>
  <arg value="sp"/>

  <config name="testVersion" value="8.1-"/>
  <config name="minimum_wp_version" value="6.5"/>

  <rule ref="WordPress"/>
  <rule ref="PHPCompatibilityWP"/>

  <rule ref="WordPress.WP.I18n">
    <properties>
      <property name="text_domain" type="array">
        <element value="my-plugin"/>
      </property>
    </properties>
  </rule>

  <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
    <properties>
      <property name="prefixes" type="array">
        <element value="my_plugin"/>
      </property>
    </properties>
  </rule>
</ruleset>

testVersion は PHPCompatibility に「PHP 8.1 以降で動くこと」を確かめさせる指定です。minimum_wp_version は、対応する WordPress の最低バージョンを伝え、それより新しい関数の使用や、非推奨になった関数の使用を判定するのに使われます。text_domain と prefixes は、翻訳関数のテキストドメインの誤りと、関数名などに接頭辞が付いていないことの検出に使います。ほかのプラグインとの名前の衝突を防ぐため、接頭辞の指定は早めに入れておくと後が楽です。

規約の中には、プロジェクトの方針と合わないものもあります。たとえば、ファイル名の付け方の規約が既存の構成と合わない場合は、その規約だけ除外します。ただし、エスケープや nonce、SQL の準備に関する指摘は、除外せずに直すべきものがほとんどです。どうしても例外にする行には // phpcs:ignore に続けて規約名と理由を書き、何をなぜ無視したのかが後から分かるようにします。

既存コードの大量の指摘にはベースラインを使う

長く使ってきたコードに初めてツールを入れると、数百から数千件の指摘が出ることも珍しくありません。全部を直してから運用を始めようとすると、いつまでも始まりません。

PHPStan には、今ある指摘を記録して、以後は新しい指摘だけを表示する「ベースライン」の機能があります。

vendor/bin/phpstan analyse --generate-baseline

phpstan-baseline.neon が作られるので、前の節の設定のように includes に追加します。これで「今日より悪くしない」状態から始められ、ベースラインに残った指摘は、そのファイルを触るときに少しずつ減らしていきます。phpcs にはこの機能が標準ではないため、まず phpcbf で自動修正できるものを直し、残りはディレクトリ単位で対象を広げていく進め方が現実的です。

phpcbf による自動修正は、多くのファイルを書き換えます。実行前に Git でコミットを済ませ、差分を確認してから取り込んでください。インデントの一括修正のような変更は、機能の変更と別のコミットに分けておくと、レビューと原因調査がしやすくなります。

GitHub Actionsで毎回実行する

手元で実行し忘れても、プルリクエストのたびに自動で確認されるようにしておくと、品質の基準が保たれます。GitHub Actions の例を示します。

# .github/workflows/quality.yml
name: Code quality
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          tools: composer
          coverage: none
      - run: composer install --no-interaction --no-progress
      - run: composer lint
      - run: composer analyse

PHP のバージョンは、本番サーバーと同じものに合わせます。アクションのメジャーバージョンは更新されることがあるため、各アクションの README で現在の推奨を確認してください（2026年10月現在）。

CI で指摘が出たら、その場で直すか、正当な理由があれば設定で除外します。指摘が出ても通過する設定にすると、だれも結果を見なくなります。失敗したら止まる設定のまま運用することが大切です。

つまずきやすい点

PHPStan がメモリ不足で止まる: --memory-limit=1G のように上限を指定します。解析対象に vendor や node_modules が含まれていないかも確認します。
WordPress の関数が「見つからない」と指摘される: szepeviktor/phpstan-wordpress が読み込まれていません。phpstan/extension-installer が入っていて、allow-plugins で許可されているかを確認します。
自作の定数やほかのプラグインの関数が見つからない: 自作の定数は PHPStan の設定で読み込むファイル（bootstrapFiles）を指定するか、スタブファイルを用意します。WooCommerce など主要なプラグインには、コミュニティが公開しているスタブのパッケージもあります。
ローカルと CI で結果が違う: ツールのバージョンが違う可能性があります。composer.lock を Git に含め、CI では composer install を使います。

まとめ

PHPStan は動作上の誤り、phpcs と WPCS は WordPress の作法と安全な書き方、PHPCompatibility は PHP のバージョン対応を見る。
ツールは Composer の require-dev に入れ、allow-plugins の許可と scripts への登録で、だれでも同じ手順で実行できるようにする。
PHPStan は低いレベルから始め、既存の指摘はベースラインで記録して新しい指摘だけを直す。
エスケープや nonce、SQL に関する指摘は除外せずに直し、例外にする行は理由を残す。
GitHub Actions で毎回実行し、失敗したら止まる設定で運用する。