Playground CLI

@wp-playground/cli は、WordPress の開発とテストのフローを簡素化するコマンドラインツールです。Playground CLI は、プラグイン、テーマ、または WordPress インストールを含むディレクトリの自動マウントをサポートしています。また、柔軟性が必要な場合は、CLI はローカル環境をカスタマイズするためのマウントコマンドもサポートしています。

主な機能:

• クイックセットアップ: わずか数秒でローカルの WordPress 環境をセットアップできます。
• 柔軟性: さまざまなシナリオに合わせて設定を調整できます。
• シンプルな環境: 追加の設定は不要で、互換性のある Node バージョンをインストールするだけですぐに使用できます。

要件

Playground CLI を使用するには、Node.js 20.18 以降が必要です。これは推奨される長期サポート (LTS) バージョンです。Node.js ウェブサイト からダウンロードできます。

クイックスタート

Playground CLI を実行するには、コマンド ラインを開いて次のコマンドを使用します。

npx @wp-playground/cli@latest server

前のコマンドでは、テスト用に新しい WordPress インスタンスしか作成されません。多くの開発者は、自分の作業をテストしたいと考えるでしょう。プラグインやテーマをテストするには、プロジェクトフォルダに移動し、--auto-mount フラグを付けて CLI を実行してください。

cd my-plugin-or-theme-directory
npx @wp-playground/cli@latest server --auto-mount

WordPress と PHP のバージョンの選択

デフォルトでは、CLI はパフォーマンス向上のため、WordPress と PHP 8.3 の最新の安定バージョンを読み込みます。希望するバージョンを指定するには、フラグ--wp=<version>と--php=<version>を使用します。

npx @wp-playground/cli@latest server --wp=6.8 --php=8.3

ブループリントの読み込み

Playground CLI 開発エクスペリエンスを次のレベルに引き上げる方法の一つは、Blueprints との統合です。この技術に馴染みのない方のために説明すると、開発者は WordPress Playground インスタンスの初期状態を設定できます。

--blueprint=<blueprint-address> フラグを使用すると、開発者はカスタム初期状態でプレイグラウンドを実行できます。以下の例でこれを行います。

(my-blueprint.json)

{
  "landingPage": "/wp-admin/options-general.php?page=akismet-key-config",
  "login": true,
  "plugins": [
    "hello-dolly",
    "https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
  ]
}

ブループリントをロードする CLI コマンド:

npx @wp-playground/cli@latest server --blueprint=my-blueprint.json

フォルダを手動でマウントする

プロジェクトによっては、特殊な構造を持つため、カスタム設定が必要となる場合があります。例えば、リポジトリに /wp-content/ フォルダ内のすべてのファイルが含まれている場合などです。このようなシナリオでは、Playground CLI に --mount フラグを使用して、プロジェクトをそのフォルダからマウントするように指定できます。

npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/MY-PLUGIN-DIRECTORY

WordPress インストール前のマウント

WordPress のインストールが始まる前に、WordPress プロジェクトファイルをマウントすることを検討してください。この方法は、Playground の起動プロセスをオーバーライドしたい場合に便利です。Playground を WP-CLI に接続するのに役立ちます。--mount-before-install フラグはこのプロセスをサポートします。

npx @wp-playground/cli@latest server --mount-before-install=.:/wordpress/

情報

Windows では、パス形式「 /host/path:/vfs/path 」が問題を引き起こす可能性があります。この問題を解決するには、「 --mount-dir 」および「 --mount-dir-before-install 」フラグを使用してください。これらのフラグを使用すると、ホストおよび仮想ファイルシステムのパスを「"/host/path"」および「"/vfs/path"」という代替形式で指定できます。

コマンドと引数

Playground CLI はシンプルで設定しやすく、固定観念にとらわれません。WordPress の設定に合わせて自由に設定できます。Playground CLI では、以下のトップレベルコマンドを使用できます。

• server: (デフォルト) ローカルの WordPress サーバーを起動します。
• run-blueprint: Web サーバーを起動せずに Blueprint ファイルを実行します。
• build-snapshot: Blueprint に基づいて WordPress サイトの ZIP スナップショットを構築します。

server コマンドは次のオプション引数をサポートしています。

• --port=<port>: サーバーが listen するポート番号。デフォルトは 9400 です。
• --outfile: ビルド時にこの出力ファイルに書き込みます。
• --wp=<version>: 使用する WordPress のバージョン。デフォルトは最新です。
• --auto-mount: 現在のディレクトリ (プラグイン、テーマ、wp-content など) を自動的にマウントします。
• --mount=<mapping>: ディレクトリを手動でマウントします (複数回使用可能)。形式: "/host/path:/vfs/path"。
• --mount-before-install: WordPress をインストールする前に、ディレクトリを PHP ランタイムにマウントします (複数回使用可能)。形式: "/host/path:/vfs/path"。
• --mount-dir: ディレクトリを PHP ランタイムにマウントします (複数回使用可能)。フォーマット: "/host/path" "/vfs/path"
• --mount-dir-before-install: WordPress をインストールする前にディレクトリをマウントします（複数回使用可能）。フォーマット: "/host/path" "/vfs/path"
• --blueprint=<path>: 実行する JSON ブループリント ファイルへのパス。
• --blueprint-may-read-adjacent-files: 同意フラグ: ローカル ブループリント内の「バンドル」リソースが、ブループリント ファイルと同じディレクトリにあるファイルを読み取ることを許可します。
• --login: ユーザーを管理者として自動的にログインします。
• --wordpress-install-mode <mode>: WordPress の準備方法を制御します。既定値は download-and-install です。他のオプション: install-from-existing-files (マウント済みのファイルを使ってインストール)、install-from-existing-files-if-needed (既存サイトを検出した場合はセットアップを省略) 、do-not-attempt-installing (WordPress をダウンロードもインストールもしません)。
• --skip-sqlite-setup: SQLite データベース統合をセットアップしません。
• --verbosity: ログと進捗メッセージを出力します。選択肢は「quiet」、「normal」、「debug」です。デフォルトは「normal」です。
• --debug: 起動中にエラーが発生した場合、PHP のエラーログを出力します。

CLI に関するサポートが必要ですか?

Playground CLI では、--help フラグを使用して、使用可能なコマンドと引数の完全なリストを取得できます。

npx @wp-playground/cli@latest --help

JavaScript によるプログラム的使用

Playground CLI は、runCLI 関数を使って JavaScript/TypeScript コードからプログラム的に制御することもできます。これにより、コード内のすべての CLI 機能に直接アクセスできるため、エンドツーエンドテストの自動化に役立ちます。runCLI の使い方の基本を説明しましょう。

特定のバージョンで WordPress インスタンスを実行する

runCLI 関数を使用すると、PHP や WordPress のバージョンなどのオプションを指定できます。以下の例では、WordPress の最新バージョンである PHP 8.3 を要求し、自動的にログインするように設定しています。サポートされているすべての引数は RunCLIArgs 型で定義されています。

import { runCLI, RunCLIArgs, RunCLIServer } from "@wp-playground/cli";

let cliServer: RunCLIServer;

cliServer = await runCLI({
    command: 'server',
    php: '8.3',
    wp: 'latest',
    login: true
} as RunCLIArgs);

上記のコードを実行するには、開発者は好みの方法を設定できます。このコードを実行する簡単な方法は、.ts ファイルとして保存し、tsx などのツールで実行することです。例: tsx my-script.ts

ブループリントの設定

ブループリントは、blueprint プロパティに直接渡されるオブジェクトリテラルとして、または外部の .json ファイルへのパスを含む文字列として、2 つの方法で提供できます。

import { runCLI, RunCLIServer } from "@wp-playground/cli";

let cliServer: RunCLIServer;

cliServer = await runCLI({
  command: 'server',
  wp: 'latest',
  blueprint: {
    steps: [
        {
          "step": "setSiteOptions",
          "options": {
              "blogname": "Blueprint Title",
              "blogdescription": "A great blog description"
          }
        }
    ],
  },
});

ブループリント オブジェクトを定義するときに完全な型安全性を確保するには、@wp-playground/blueprints パッケージから BlueprintDeclaration 型をインポートして使用できます。

import type { BlueprintDeclaration } from '@wp-playground/blueprints';

const myBlueprint: BlueprintDeclaration = {
  landingPage: "/wp-admin/",
  steps: [
    {
      "step": "installTheme",
      "themeData": {
        "resource": "wordpress.org/themes",
        "slug": "twentytwentyone"
      },
      "options": {
        "activate": true
      }
    }
  ]
};

プログラムによるプラグインのマウント

runCLI を使用することで、プログラム的にローカルディレクトリをマウントできます。mount および mount-before-install オプションが利用可能です。hostPath プロパティには、ローカルマシン上のディレクトリへのパスを指定します。このパスは、スクリプトが実行される場所からの相対パスである必要があります。

	cliServer = await runCLI({
      command: 'server',
      login: true,
      'mount-before-install': [
        {
          hostPath: './[my-plugin-local-path]',
          vfsPath: '/wordpress/wp-content/plugins/my-plugin',
        },
      ],
    });

これらのオプションを使用すると、プロジェクトの取り付け部分をブループリントと組み合わせることができます。例:

import { runCLI, RunCLIArgs, RunCLIServer } from "@wp-playground/cli";

let cliServer: RunCLIServer;

cliServer = await runCLI({
    command: 'server',
    php: '8.3',
    wp: 'latest',
    login: true,
    mount: [
        {
            "hostPath": "./plugin/",
            "vfsPath": "/wordpress/wp-content/plugins/playwright-test"
        }
    ],
    blueprint: {
        steps: [
            {
                "step": "activatePlugin",
                "pluginPath": "/wordpress/wp-content/plugins/playwright-test/plugin-playwright.php"
            }
        ]
    }
} as RunCLIArgs);