@wordpress/env

wp-env を使用してプラグインやテーマのビルド用とテスト用の WordPress ローカル環境を簡単にセットアップできます。シンプルにインストールできて構成する必要もありません。

クイック (tl;dr) インストラクション

Docker が動作していることを確認し、以下のコマンドを実行してください。

$ cd /path/to/a/wordpress/plugin
$ npm -g i @wordpress/env
$ wp-env start

http://localhost:8888 (ユーザー名: admin、パスワード: password) でローカル環境が利用できます。

前提ソフトウエア

wp-env を使用するにはまず Docker をインストールしてください。インストールの詳細については以下の OS ごとのドキュメントを参照してください。Windows 10 ProWindows の他のバージョンmacOSLinux

Node.js と NPM も必要です。wp-env の開発には最新の LTS バージョンの Node.js を使用しているため、これを推奨します。

インストール

グローバルパッケージとしてのインストール

前提ソフトウエアをインストールを確認できたら、グローバルに wp-env をインストールできます。

$ npm -g i @wordpress/env

これで wp-env を使うことができます !

ローカルパッケージとしてのインストール

プロジェクトにすでに package.json がある場合、wp-env をローカルパッケージとして使用することもできます。まず wp-env を開発依存としてローカルにインストールします。

$ npm i @wordpress/env --save-dev

次に package.json を変更し、npm scripts (https://docs.npmjs.com/misc/scripts) にコマンドを追加します。

"scripts": {
    "wp-env": "wp-env"
}

この方法で wp-env をインストールした場合、この文書で説明するすべての wp-env コマンドの前に npm run を追加してください。たとえば

# wp-env に "update" を渡すには別のダッシュ(-)を追加する必要があります。
$ npm run wp-env start -- --update

と実行します。以後は次のような形式のみ記述します。

$ wp-env start --update

使用方法

環境の開始

まず Docker が実行されていることを確認してください。確認するにはシステムトレイ、またはメニューバーの Docker アイコンをクリックします。

次に WordPress プラグインやテーマを含むディレクトリーに移動してください。

$ cd ~/gutenberg

ローカル環境を開始します。

$ wp-env start

Web ブラウザーで http://localhost:8888 を開きます。ローカルのプラグインやテーマがインストール、有効化された状態で WordPress が表示されます。デフォルトのログインアカウントはユーザー名 admin、パスワード password です。

環境の停止

ローカル環境を停止するには以下を実行します。

$ wp-env stop

一般的な問題のトラブルシューティング

以下のトラブルシューティングを順に実行することで多くの一般的な問題を解決できます。

1. wp-env が動作していることの確認

まず wp-env が動作していることを確認します。現在実行中の Docker コンテナ一覧を出力します。

$ docker ps

リストに3つのエントリーが表示されます。ポート 8888 の wordpress、ポート 8889 の tests-wordpress、ポート 3306 の mariadb です。

2. ポート番号の確認

デフォルトでは wp-env はポート 8888 を使用し、ローカル環境が http://localhost:8888 で利用可能になります。

別のサーバーと衝突しないように wp-env の使用するポートを構成できます。wp-env を開始する際に WP_ENV_PORT 環境変数を指定してください。

$ WP_ENV_PORT=3333 wp-env start

docker ps を実行し PORTS 列を参照すると、現在 wp-env がどのポートを使用しているかを調べることができます。

.wp-env.json ファイル内にポート番号を指定することもできますが、環境変数が指定されるとそちらが優先されます。

3. wp-env の再起動

wp-env を再起動すると、内部で使用される Docker コンテナが再起動され、多くの問題を解消します。

wp-env を再起動するには、

$ wp-env stop
$ wp-env start

4. Docker の再起動

Docker を再起動すると、内部で使用する Docker コンテナとボリュームが再起動され、多くの問題を解消します。

Docker を再起動するには

  1. システムトレイ、または、メニューバーの Docker アイコンをクリックする。
  2. Restart を選択する。

Docker の再起動後、wp-env を起動します。

$ wp-env start

5. データベースのリセット

ローカル環境の使用するデータベースをリセットすると、多くの問題、特に WordPress のインストールに関する問題が解消します。

データベースをリセットするには

⚠️ 警告: 次のコマンドは、ローカル WordPress 環境内の投稿、ページ、メディア等を完全に削除します。

$ wp-env clean all
$ wp-env start

6. すべてを破壊して、最初からやり直す 🔥

上のすべてがうまくいかない場合、ローカルの Docker コンテナとボリューム、WordPress ディレクトリーを強制的に削除して、ゼロからやり直してみてください。

すべてを破壊するには

⚠️ 警告: 次のコマンドは、ローカル WordPress 環境内の投稿、ページ、メディア等を完全に削除します。

$ wp-env destroy
$ wp-env start

7. デバッグモードと生成された docker ファイルの確認

wp-env は裏側で docker を使用しています。生成された docker-compose ファイルを調べると何が起きているかを理解できます。

wp-env をデバッグモードで開始します。

wp-env start --debug

wp-env dockerComposeConfigPath を含む構成情報を出力します。

ℹ Config:
    ...
    "dockerComposeConfigPath": "/Users/$USERNAME/.wp-env/5a619d332a92377cd89feb339c67b833/docker-compose.yml",
    ...

コマンドリファレンス

wp-env は生成したファイルを wp-env ホームディレクトリー、デフォルトでは ~/.wp-env に置きます。例外は Linux で Snap パッケージの互換性のため、ファイルは ~/wp-env に置かれます。wp-env ホームディレクトリーには各プロジェクトのサブディレクトリーが /$md5_of_project_path として作成されます。wp-env ホームディレクトリーを変更するには、WP_ENV_HOME 環境変数を設定してください。例えば WP_ENV_HOME="something" wp-env start と実行すると、プロジェクトファイルは現行ディレクトリーからの相対パスでディレクトリー ./something/$md5_of_project_path にダウンロードされます。

wp-env start

start コマンドは WordPress 環境をインストールし初期化します。これには指定された任意のリモートのソースのダウンロードも含まれます。wp-env はデフォルトでは構成ファイルが変更されない限り、環境を更新も再考性もしません。ソースを更新し、構成オプションを再度適用するには wp-env start --update を使用してください。既存のコンテンツは上書きされません。

wp-env start

WordPress 開発環境をポート 8888 (​http://localhost:8888​) で (ポートは WP_ENV_PORT で指定可)、
テスト環境を 8889 (​http://localhost:8889​) で (ポートは WP_ENV_TESTS_PORT で指定可) 開始します。
コマンドは WordPress インストールディレクトリー、プラグインやテーマのディレクトリー、
または .wp-env.json ファイルのあるディレクトリーで実行する必要があります。最初のインストール後、
'--update' フラグを使用して更新をマップされたソースにダウンロードし、WordPress 構成オプションに
再適用します。

引数:
  --update   ソースの更新をダウンロードし、WordPress 構成に適用する
                                                      [boolean] [デフォルト: false]

wp-env stop

wp-env stop

実行中の WordPress 開発環境、テスト環境を停止し、ポートを解放します。

wp-env clean

wp-env clean [environment]

WordPress データベースをクリアします。

引数:
  environment  どの環境のデータベースをクリアするか。
            [string] [選択: "all", "development", "tests"] [デフォルト: "tests"]

wp-env run

wp-env run <container> [command..]

動作している Docker コンテナの任意のコマンドを実行します。たとえば wp cli コマンドを実行する際に便利です。
また bash のようなシェルセッションや、WordPress インスタンス内の WordPress シェルを開くためにも
使用できます。たとえば `wp-env run cli bash` は開発 WordPress インスタンス内で bash を開きます。

引数:
  container  コマンドを実行するコンテナ        [string] [必須]
  command    実行するコマンド                [array] [デフォルト: []]

オプション:
  --help     ヘルプの表示                                              [boolean]
  --version  バージョン番号の表示                                       [boolean]
  --debug    デバッグ出力の有効化                     [boolean] [でファルト: false]

例:

wp-env run cli wp user list
⠏ Running `wp user list` in 'cli'.

ID      user_login      display_name    user_email      user_registered roles
1       admin   admin   wordpress@example.com   2020-03-05 10:45:14     administrator

✔ Ran `wp user list` in 'cli'. (in 2s 374ms)
wp-env run tests-cli wp shell
ℹ Starting 'wp shell' on the tests-cli container. Exit the WordPress shell with ctrl-c.

Starting 31911d623e75f345e9ed328b9f48cff6_mysql_1 ... done
Starting 31911d623e75f345e9ed328b9f48cff6_tests-wordpress_1 ... done
wp> echo( 'hello world!' );
hello world!
wp> ^C
✔ Ran `wp shell` in 'tests-cli'. (in 16s 400ms)

wp-env destroy

wp-env destroy

WordPress 環境を破壊します。WordPress 環境と関連する Docker コンテナ、ボリューム、
ネットワークを削除し、ローカルファイルを削除します。

wp-env logs

wp-env logs [environment]

指定した WordPress 環境の PHP と Docker のログを表示します。

引数:
  environment  どの環境のログを出力するか
      [string] [選択: "development", "tests", "all"] [デフォルト: "development"]

オプション:
  --help     ヘルプの表示                [boolean]
  --version  バージョン番号の表示         [boolean]
  --debug    デバッグ出力の有効化         [boolean] [デフォルト: false]
  --watch    ログをウオッチする          [boolean] [デフォルト: true]

.wp-env.json

WordPress のインストールや開発環境で使用するプラグインやテーマをカスタマイズできます。.wp-env.json ファイルに指定し、同じディレクトリーで wp-env を実行してください。

.wp-env.json はテストと開発の両方のインスタンスに適用可能なオプションとして、6つのフィールドをサポートします。

フィールドタイプデフォルト説明
"core"string|nullnull使用する WordPress のバージョンまたはビルド。null の場合、最新リリース版
"plugins"string[][]環境にインストール、有効化するプラグインのリスト
"themes"string[][]環境にインストールするテーマのリスト。最初のテーマが有効化される
"port"integer8888 (テストインスタンスでは 8889)インストールに使用するポート番号。インスタンスには ‘http://localhost:8888’ でアクセスできる
"config"Object"{ WP_DEBUG: true, SCRIPT_DEBUG: true }"wp-config.php の定数とその値
"mappings"Object"{}"WordPress インスタンス内にマウントされるローカルディレクトリと WordPress ディレクトリのマッピング

注意: ポート番号に関する環境変数 (WP_ENV_PORT と WP_ENV_TESTS_PORT) は .wp-env.json の値に優先します。

corepluginsthemesmappings フィールドに指定できる文字列のタイプを以下に示します。

タイプ形式
相対パス.<path>|~<path>"./a/directory""../a/directory""~/a/directory"
絶対パス/<path>|<letter>:\<path>"/a/directory""C:\\a\\directory"
GitHub リポジトリ<owner>/<repo>[#<ref>]"WordPress/WordPress""WordPress/gutenberg#master"
ZIP ファイルhttp[s]://<host>/<path>.zip"https://wordpress.org/wordpress-5.4-beta2.zip"

リモートのソースは ~/.wp-env 内の一時ディレクトリーにダウンロードされます。

さらにキー env は上の任意のオプションを個々の環境ごとに上書きできます。たとえば次の .wp-env.json ファイルでは

{
    "plugins": [ "." ],
    "config": {
        "KEY_1": true,
        "KEY_2": false
    },
    "env": {
        "development": {
            "themes": [ "./one-theme" ]
        },
        "tests": {
            "config": {
                "KEY_1": false
            },
            "port": 3000
        }
    }
}

development インスタンスでは、cwd がプラグインに、one-theme がテーマにマップされ、KEY_1 が true に、KEY_2 が false に設定されます。デフォルトのポートは引き続き 8888 が使用されます。

tests インスタンスでは、cwd がプラグインマップされますがテーマのマップはありません。また KEY_2 は false のままですが、KEY_1 は false で、デフォルトのポートは 3000 で上書きされます。

この強力な機能により環境ごとにオプションを変更できます。

.wp-env.override.json

このファイルのフィールド値は、.wp-env.json の値よりも優先されます。このファイルをバージョンコントロールの対象外とすると、常に希望のローカル環境で上書きできて便利です。注意: plugins や themes などのオプションはマージされません。結果として .wp-env.override.json ファイル内で plugins を設定すると、ベースレベルの構成でリストされたすべてのプラウグインを上書きします。マージされるキーは config と mappings のみです。すなわちデフォルト値を失うこと無く自身の wp-config 値を設定できます。

デフォルト wp-config 値

development インスタンスでは次の wp-config 値がデフォルトとして定義されます。

WP_DEBUG: true,
SCRIPT_DEBUG: true,
WP_PHP_BINARY: 'php',
WP_TESTS_EMAIL: 'admin@example.org',
WP_TESTS_TITLE: 'Test Blog',
WP_TESTS_DOMAIN: 'http://localhost',
WP_SITEURL: 'http://localhost',
WP_HOME: 'http://localhost',

tests インスタンスでは同じすべての値が定義されますが、WP_DEBUG と SCRIPT_DEBUG は false に設定されます。

また URL を参照する値には環境で指定されたポート番号が含まれます。たとえば testsPort: 3000, port: 2000 を設定すると、WP_HOME は tests インスタンスでは http://localhost:3000、development インスタンスでは http://localhost:2000 になります。

最新のリリース版 WordPress + 現行ディレクトリーのプラグインをインストールし有効化

この設定はプラグイン開発時に便利です。

{
    "core": null,
    "plugins": [ "." ]
}

最新の開発版 WordPress + 現行ディレクトリーのプラグインをインストール

この設定はプラグイン開発時に、最新のコアの変更の影響を見る上で便利です。

{
    "core": "WordPress/WordPress#master",
    "plugins": [ "." ]
}

ローカルの wordpress-develop + 現行ディレクトリーのプラグインをインストール

プラグインと WordPress コアで同時に作業する場合に便利です。

{
    "core": "../wordpress-develop/build",
    "plugins": [ "." ]
}

完全なテスト環境

インテグレショーンテストで便利です。古いバージョンの WordPress と異なるプラグインの組み合わせで互いに与える影響をテストできます。

{
    "core": "WordPress/WordPress#5.2.0",
    "plugins": [ "WordPress/wp-lazy-loading", "WordPress/classic-editor" ],
    "themes": [ "WordPress/theme-experiments" ]
}

mu-plugins とマッピングディレクトリの追加

マッピング構成を使用して mu-plugins を追加できます。マッピング構成を使用すると、WordPress インストール内の任意の場所にディレクトリをマウントできます。サブディレクトリにマウントすることも可能です。ただし以下の例で theme-1 は「最初」のマップされたテーマですが、有効化されないことに注意してください。

{
    "plugins": [ "." ],
    "mappings": {
        "wp-content/mu-plugins": "./path/to/local/mu-plugins",
        "wp-content/themes": "./path/to/local/themes",
        "wp-content/themes/specific-theme": "./path/to/local/theme-1"
    }
}

インスタンスのプラグインやテーマを有効化しない

デフォルトでは plugins キーのすべてのプラグインは有効化されます。この動きを避けるには mappings キーを使用してください。この方法は常には有効化すべきでない、テスト用のプラグインがある場合に便利です。同じことは有効化すべきでないテーマにも当てはまります。

{
    "plugins": [ "." ],
    "mappings": {
        "wp-content/plugins/my-test-plugin": "./path/to/test/plugin"
    }
}

テスト環境にのみプラグインをマップする

1つの環境でのみプラグインを有効化し、他の環境では有効化しない場合、env.<envName> を使用して1つの環境でのみオプションを設定できます。ここではテストインスタンスでのみ現行ディレクトリとテストプラグインを有効化しています。他のインスタンスではプラグインは有効化されません。

{
    "plugins": [ "." ],
    "env": {
        "tests": {
            "plugins": [ ".", "path/to/test/plugin" ]
        }
    }
}

カスタムポート番号

wp-env にカスタムポート番号を指定することで、他の wp-env インスタンスとの衝突を避けられます。

{
    "plugins": [ "." ],
    "port": 4013,
    "env": {
        "tests": {
            "port": 4012
        }
    }
}

原文

Code is Poetry.

最終更新日: