WordPressプラグインを修正するたびに、テスト用のサイトを用意し直すのは手間がかかります。wp-envを使うと、wp-env startの1コマンドで、プラグインをマウントしたWordPress環境をDockerで立ち上げられます。この記事では、既存プラグインの開発環境をwp-envで整える手順を解説します。

wp-envとは

wp-envは、npmパッケージ@wordpress/envとして提供されている、Dockerベースのローカル開発環境ツールです。WordPress本体、プラグイン、テーマ、wp-config.phpの定数を.wp-env.jsonに宣言すると、その内容どおりの環境が起動します。操作はCLIだけなので、CIでも同じ手順で環境を作れます。

事前準備

次のツールを用意します。

• Node.js 18.12以上（公式ドキュメントでは最新のLTS版を推奨）
• Docker
• Git

Gitはwp-envがGitHubなどからWordPressやプラグインをダウンロードするときに使います。開発対象のプラグインをGitで管理している必要はありません。以降の例ではhello-worldというプラグインを使うので、そのディレクトリへ移動しておきます。

cd hello-world

プロジェクトの構成を確認する

プラグインのコードがあるディレクトリで、そのままwp-envを起動します。

hello-world/
├── hello-world.php  ← プラグイン本体
├── inc/
├── assets/
└── readme.txt

.wp-env.jsonがなくても、ディレクトリ直下のPHPファイルにプラグインヘッダー（Plugin Name:）があれば、wp-envはプラグインと判定します。テーマの場合はTheme Name:が目印です。判定できないときは、起動時にWarning: could not find a .wp-env.json configuration fileで始まる警告が出ます。複数のプラグインをまとめて管理するモノレポでは、.wp-env.jsonで個別に指定します。

.wp-env.jsonを作成する

プロジェクトのルートに.wp-env.jsonを置きます。すでにある場合、この手順は不要です。

{
  "plugins": ["."],
  "config": {
    "WP_DEBUG": true,
    "SCRIPT_DEBUG": true
  }
}

主な設定項目は次のとおりです。

• core: 使うWordPressを指定します。省略すると最新の正式リリースが使われます。GitHubのリポジトリとタグ、ブランチはWordPress/WordPress#6.5.2の形式で指定します。
• pluginsとthemes: 相対パス、絶対パス、GitHubリポジトリ、ZIPファイルのURLを指定できます。pluginsに書いたプラグインは、起動時に有効化されます。
• config: wp-config.phpに定義する定数です。WP_DEBUGとSCRIPT_DEBUGをtrueにすると、デバッグ表示が有効になり、JavaScriptとCSSは縮小されていないファイルが読み込まれます。
• mappings: WordPressのディレクトリとローカルのディレクトリの対応を、オブジェクトで指定します。"wp-content/mu-plugins": "./mu-plugins"のように書くと、ローカルのディレクトリをmu-pluginsとしてマウントできます。

wp-envは.wp-env.jsonをJSONとして読み込むため、ファイルにコメントは書けません。

開発環境を起動する

wp-envをインストールして、起動します。

# wp-envをインストール（初回のみ）
npm install -g @wordpress/env

# 開発環境を起動
wp-env start

初回はイメージの取得とコンテナの作成が入るため、時間がかかります。完了すると、次のようなメッセージが表示されます。MySQLのポート番号はDockerが割り当てます。

WordPress development site started at http://localhost:8888
MySQL is listening on port 32768
WordPress test site started at http://localhost:8889
MySQL for automated testing is listening on port 32769

✔ Done!

ブラウザでhttp://localhost:8888/wp-admin/を開き、ユーザー名admin、パスワードpasswordでログインします。プラグインが有効化されていれば、環境は整っています。プラグインのディレクトリがマウントされているので、ファイルを保存してブラウザをリロードすれば、変更を確認できます。

よく使うコマンド

開発中によく使うコマンドは次のとおりです。

コマンド	目的
wp-env run cli "wp plugin list"	WP-CLIを直接実行する
wp-env run tests-cli --env-cwd=wp-content/plugins/hello-world phpunit	テスト用のコンテナでPHPUnitを実行する
wp-env stop	環境を停止する
wp-env destroy	コンテナ、ボリューム、ファイルを削除する

CIで使う

CIでも同じ設定ファイルで環境を作れます。GitHub Actionsの例です。

- uses: actions/checkout@v7
- run: npm install -g @wordpress/env
- run: wp-env start --update
- run: wp-env run cli "wp core version"
- run: wp-env run tests-cli --env-cwd=wp-content/plugins/hello-world phpunit

ハマりやすい点

起動まわりで引っかかりやすい点と対処です。

症状	原因と対処
Warning: could not find a .wp-env.jsonで始まる警告が出る	ルートをプラグインかテーマと判定できていません。.wp-env.jsonを置くか、プラグインのディレクトリで実行します。
データベースを初期化したい	wp-env reset developmentを実行します。テスト用も初期化するならwp-env reset allです。
8888番ポートが使用中で起動できない	.wp-env.jsonに"port": 9001を追加します。テスト用は"testsPort"です。環境変数WP_ENV_PORTでも指定できます。

まとめ

wp-envを使うと、.wp-env.jsonでプラグイン、テーマ、定数を宣言するだけで、Dockerの上にWordPressの開発環境を用意できます。CLIで操作するため、ローカルとCIで同じ設定ファイルを使えます。既存のプラグインでも、プラグインのディレクトリでwp-env startを実行するだけで導入できます。