• HOME
  • WPCS（WordPress Coding Standards）をプラグイン開発に導入する手順

2026年9月1日

  • シェア
  • ツイート

    • 2026年9月1日

    WPCS（WordPress Coding Standards）をプラグイン開発に導入する手順

    WPCS（WordPress Coding Standards、正式名はWordPressCS）は、PHPのコード検査ツール「PHP_CodeSniffer」（PHPCS）に、WordPressの書き方の決まりを教え込むためのルール集です。インデントや空白といった見た目だけでなく、入力値の無害化（サニタイズ）漏れ、出力時のエスケープ漏れ、関数名の接頭辞の付け忘れ、翻訳関数のテキストドメインの誤りなども指摘してくれます。

    この記事では、プラグインのフォルダーにWPCSを入れて検査し、自動で直し、コミット時とGitHub上で自動検査するまでを説明します。コマンドと設定ファイルは、WPCS 3.4.1（PHP_CodeSniffer 3.13）で動作を確かめています（2026年10月時点）。

    WPCSとほかのツールの関係

    名前が似たツールがあるため、最初に整理しておきます。

    名前 役割
    PHP_CodeSniffer コード検査の本体。phpcs（検査）と phpcbf（自動修正）の2つのコマンドを持つ
    WPCS（WordPressCS） PHP_CodeSniffer用のWordPress向けルール集
    PHP-CS-Fixer 別のプロジェクトが作っている整形ツール。WPCSとは無関係

    WPCSを入れると、PHP_CodeSnifferも一緒に入ります。使うコマンドは phpcs と phpcbf です。

    必要なもの

    • PHP 7.2以上（拡張機能 Filter・libxml・Tokenizer・XMLReader が有効なこと。iconv と mbstring も推奨）
    • Composer

    WPCS 3.0以降、公式に案内されている導入方法はComposerだけです。

    手順1：Composerで導入する

    プラグインのフォルダー（composer.json を置く場所）で、次の2行を実行します。

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

    1行目は、ルール集をPHP_CodeSnifferに自動登録するComposerプラグインの実行を許可する設定です。これを先に入れておかないと、Composerが許可を求めて止まったり、ルール集が登録されなかったりします。

    導入できたかは、登録されているルール集の一覧で確かめます。

    vendor/bin/phpcs -i

    一覧に WordPress、WordPress-Core、WordPress-Docs、WordPress-Extra が出ていれば成功です。

    ルール集 内容
    WordPress 下の3つを含む、すべてのルール
    WordPress-Core WordPress本体のコーディング規約
    WordPress-Docs ドキュメントコメント（DocBlock）の書き方
    WordPress-Extra Coreに加えて、推奨される書き方のルール

    手順2：設定ファイル .phpcs.xml.dist を作る

    毎回 --standard=WordPress のように指定する代わりに、プラグインのフォルダーに設定ファイルを置きます。ファイル名を .phpcs.xml.dist（または phpcs.xml.dist、.phpcs.xml、phpcs.xml）にすると、PHP_CodeSnifferが自動で読み込みます。

    <?xml version="1.0"?>
<ruleset name="My Sample Plugin">
	<description>My Sample Plugin のコーディング規約</description>

	<!-- 検査する場所と、除外する場所 -->
	<file>.</file>
	<exclude-pattern>/vendor/*</exclude-pattern>
	<exclude-pattern>/node_modules/*</exclude-pattern>

	<!-- PHPファイルだけを対象にし、相対パスで表示、8並列、進行状況とルール名を表示 -->
	<arg name="extensions" value="php"/>
	<arg name="basepath" value="."/>
	<arg name="parallel" value="8"/>
	<arg value="ps"/>

	<!-- WordPress のすべてのルールを使う -->
	<rule ref="WordPress"/>

	<!-- 対応する WordPress の最低バージョン -->
	<config name="minimum_wp_version" value="6.7"/>

	<!-- 翻訳関数で使ってよいテキストドメイン -->
	<rule ref="WordPress.WP.I18n">
		<properties>
			<property name="text_domain" type="array">
				<element value="my-sample-plugin"/>
			</property>
		</properties>
	</rule>

	<!-- 関数名・クラス名などに付ける接頭辞 -->
	<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
		<properties>
			<property name="prefixes" type="array">
				<element value="my_sample_plugin"/>
			</property>
		</properties>
	</rule>
</ruleset>

    my-sample-plugin と my_sample_plugin は、自分のプラグインのテキストドメインと接頭辞に置き換えます。この2つを設定しておくと、他のプラグインと名前がぶつかる関数や、テキストドメインの書き間違いを検出できます。

    最初から WordPress のすべてのルールで指摘が多すぎる場合は、WordPress-Extra から始め、慣れてから WordPress-Docs を足す方法もあります。

    手順3：検査して、自動で直す

    設定ファイルがあるフォルダーで、引数なしで実行します。

    # 検査する
vendor/bin/phpcs

# 自動で直せるものを直す
vendor/bin/phpcbf

    たとえば、次のようなコードを検査したとします。

    <?php
/**
 * Plugin Name: My Sample Plugin
 * Text Domain: my-sample-plugin
 */

function show_notice(){
    $name = $_GET['name'];
    echo '<p>' . __( 'Hello', 'my-sample-plugin' ) . ' ' . $name . '</p>';
}
add_action( 'admin_notices', 'show_notice' );

    この例では、次のような指摘が出ます（抜粋）。

    • 関数名に接頭辞が無い（WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound）
    • インデントに空白を使っている（タブを使う決まり）
    • $_GET['name'] が存在するか確かめていない、wp_unslash() していない、サニタイズしていない
    • __() と $name をエスケープせずに出力している
    • ノンス（nonce）の確認なしにフォームの値を扱っている（警告）

    [x] の印が付いた指摘（空白やインデントなど）は phpcbf で直せます。セキュリティに関わる指摘は自動では直らないため、自分で書き直します。直した後のコードは次のとおりで、これは指摘0件になります。

    <?php
/**
 * Plugin Name: My Sample Plugin
 * Text Domain: my-sample-plugin
 *
 * @package My_Sample_Plugin
 */

/**
 * 管理画面にあいさつを表示する。
 */
function my_sample_plugin_show_notice() {
	// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- 表示のみで保存処理はしない。
	$name = isset( $_GET['name'] ) ? sanitize_text_field( wp_unslash( $_GET['name'] ) ) : '';
	echo '<p>' . esc_html__( 'Hello', 'my-sample-plugin' ) . ' ' . esc_html( $name ) . '</p>';
}
add_action( 'admin_notices', 'my_sample_plugin_show_notice' );

    指摘を意図的に無視するとき

    ルールに合わない正当な理由がある行だけは、コメントで指摘を止められます。上の例のように、止めるルール名と理由を書いておくと、後から読む人が判断できます。

    <?php
// 次の1行だけ、指定したルールを止める。
// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- 理由を書く。

// 範囲で止めて、再開する。
// phpcs:disable WordPress.WP.AlternativeFunctions
// ...
// phpcs:enable WordPress.WP.AlternativeFunctions

    ルール名は、-s を付けて実行したとき（上の設定ファイルでは <arg value="ps"/> で常に付けています）の表示で確かめられます。

    Composerのスクリプトに登録する

    composer.json に次のように書くと、composer lint、composer format で実行できるようになり、チームで同じコマンドを使えます。

    {
    "scripts": {
        "lint": "phpcs",
        "format": "phpcbf"
    }
}

    既にある composer.json の "scripts" の欄に、2行を追加します。

    手順4：コミットの前に自動で検査する

    Gitの pre-commit フックを使うと、コミットするPHPファイルに指摘があるときにコミットを止められます。.git/hooks/pre-commit という名前で次のファイルを作り、実行権限を付けます。

    #!/bin/sh
# コミットする PHP ファイルだけを WPCS で確認する
FILES=$(git diff --cached --name-only --diff-filter=ACM -- '*.php')
if [ -z "$FILES" ]; then
	exit 0
fi

vendor/bin/phpcs $FILES
STATUS=$?
if [ $STATUS -ne 0 ]; then
	echo "WPCS の指摘があります。vendor/bin/phpcbf で直せるものは自動で直せます。"
fi
exit $STATUS
    chmod +x .git/hooks/pre-commit

    ファイルを指定して実行した場合も、.phpcs.xml.dist の設定（ルール集やテキストドメインなど）はそのまま使われます。

    .git/hooks の中身はリポジトリに含まれないため、チームの全員に同じフックを使ってもらうには、各自で置いてもらう必要があります。全員の変更を漏れなく検査したい場合は、次のGitHub Actionsでの検査を併用します。ファイル名に空白を含むPHPファイルがあると、この簡易なスクリプトは正しく動きません。

    手順5：GitHub Actionsで自動検査する

    プッシュやプルリクエストのたびにGitHub上で検査するには、.github/workflows/wpcs.yml を作ります。

    name: WPCS

on:
  push:
  pull_request:

jobs:
  phpcs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          tools: composer

      - run: composer install --no-interaction --no-progress

      - run: vendor/bin/phpcs

    phpcs は指摘が1件でもあると0以外の終了コードで終わるため、ジョブが失敗し、プルリクエストの画面で分かります。警告（WARNING）だけでは失敗させたくない場合は、最後の行を次のようにします。

    vendor/bin/phpcs --runtime-set ignore_warnings_on_exit 1

    composer.lock をリポジトリに含めておくと、ローカルとGitHub Actionsで同じバージョンのWPCSが使われ、結果がずれにくくなります。

    既存のプラグインに後から導入するとき

    長く開発してきたプラグインに導入すると、指摘が数百件になることがあります。次の順に進めると負担を減らせます。

    1. vendor/bin/phpcbf で、自動で直せる空白やインデントの指摘をまとめて直し、その変更だけで1つのコミットにする
    2. セキュリティに関わる指摘（WordPress.Security で始まるもの）を優先して手で直す
    3. 残りの指摘は、ファイルを触るたびに少しずつ直す。急ぐ場合は設定ファイルで一時的に除外し、除外した理由をコメントに残す

    phpcbf は多くのファイルを書き換えるため、実行前に作業中の変更をコミットしておき、実行後に差分を確かめてからコミットします。

    まとめ

    • WPCSはPHP_CodeSniffer用のWordPress向けルール集で、phpcs で検査し phpcbf で自動修正する。PHP-CS-Fixerとは別物
    • 導入は composer config allow-plugins... と composer require --dev wp-coding-standards/wpcs:"^3.0" の2行
    • .phpcs.xml.dist にルール集、テキストドメイン、接頭辞を書いておけば、引数なしの vendor/bin/phpcs で検査できる
    • サニタイズ・エスケープなどセキュリティに関わる指摘は自動では直らないため、手で書き直す
    • コミット前の検査は pre-commit フック、チーム全体の検査は GitHub Actions で行う

    関連記事:

    Views: 32

    お気軽にご相談ください

    お見積りへ お問い合わせへ
    閉じる
    ▲