WordPress Playground CLI ～ローカル環境で試すPlayground～

前回の記事で紹介したWordPress Playgroundをローカル環境で実行できるのがWordPress Playground CLIです。

今回はこのWordPress Playground CLIを試してみます。

WindowsのWSL2環境で試した記録なので、別環境ではパス等が違う可能性がありますのでご留意ください。

WordPress Playground CLIの仕組み（Web版との違い）

基本的には同じコア技術 PHP.wasm（PHPをWebAssemblyにコンパイルしたもの）がベースですが、実行環境が異なります。

Web版

• PHP.wasmの実行環境：ブラウザのJavaScriptエンジン

• データの保存先：ブラウザのOPFS

• 外部ネットワークアクセス：制限あり

CLI版

• PHP.wasmの実行環境：Node.js内(@php-wasm/nodeパッケージ)

• データの保存先：ローカルファイルシステム(~/.wordpress-playground/sites/...)、指定ディレクトリと紐づけるマウント機能あり

• 外部ネットワークアクセス：Node.js経由でより柔軟

DBがSQLite、Blueprint指定で初期設定ができる、などの仕組みは共通です。

WordPress Playground CLIを起動する

所定のフォルダに移動して、npxコマンドを打って起動します。

なお、Node.js環境が必要なので、予めインストールしておきます。公式サイトには、Node.js 20.18以上でLTSが推奨と記載されているのでそれに従いましょう。（今回はNode.js 22.19.0で進めました）

今回は /home/hoge/projects/playground-cli-demo というディレクトリで作業していきます。（hogeユーザの project/playground-cli-demo ディレクトリ）

起動前に動作確認

まず、helpオプションを付けて起動しましょう。

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

初回は続けて良いか確認が出るのでそのまま y を入力します。

Need to install the following packages:
@wp-playground/cli@3.1.47
Ok to proceed? (y)

問題無ければ、コマンドとオプションの一覧が表示されます。

Usage: wp-playground <command> [options]

コマンド:
  wp-playground-cli start           Start a local WordPress server with automatic project detection (recommend
                                    ed)
  wp-playground-cli server          Start a local WordPress server (advanced, low-level)
  wp-playground-cli run-blueprint   Execute a Blueprint without starting a server
  wp-playground-cli build-snapshot  Build a ZIP snapshot of a WordPress site based on a Blueprint
  wp-playground-cli php             Run a PHP script

オプション:
  --help     ヘルプを表示                                                                                       [真偽]
  --version  バージョンを表示                       

コマンド体系は5つ: start（推奨・自動プロジェクト検出）、server（低レベル・詳細指定用）、run-blueprint（Blueprintのみ実行）、build-snapshot（サイトのZIPスナップショット作成）、php（PHPスクリプト実行）、のようです。

startコマンドで起動

startコマンドを付けて起動をします。

npx @wp-playground/cli@latest start

無事起動しました。

npx @wp-playground/cli@latest start
Site files stored at: /home/hoge/.wordpress-playground/sites/0f47879d36b338f9d0363c028b63f38e67e8d8585242e436c604887b2ff62ce5

WordPress Playground CLI

PHP 8.3  WordPress latest
Extensions intl
Mount /home/hoge/.wordpress-playground/sites/0f47879d36b338f9d0363c028b63f38e67e8d8585242e436c604887b2ff62ce5 → /wordpress

Logging in 100%

Ready! WordPress is running on <http://127.0.0.1:9400> (6 workers)

トラブル発生

http://127.0.0.1:9400 にWindows側のブラウザからアクセスすると、「このサイトにアクセスできません 127.0.0.1 で接続が拒否されました。」とエラーメッセージが出て表示されません。

どうやらhttp://127.0.0.1:9400にはWSL2の内部からはアクセスできるが（WSL2側のcurlコマンドでは出力される）、Windows側からアクセスできない、という状況のようです。

ところが不思議なことに http://localhost:9400 はアクセスできるのでした。（ただしWordPressのsite_url が http://127.0.0.1:9400 のままなので表示は崩れています）

いろいろ調査してみたのですが、解決しなかったので、http://localhost:9400 のURLで起動できるようにしてみます。

--site-url オプションを付けて起動しなおします。（もし起動中の場合は Ctrl+Cで停止しておきます）

--reset を付けているのは、構築済みのDBもリセットするためです。

npx @wp-playground/cli@latest start --site-url=http://localhost:9400 --reset

ブラウザで http://localhost:9400 にアクセスすると、無事表示できました。（なお、起動後のログは相変わらず http://127.0.0.1:9400 のままなので読み替えて進めます）

なおこちらのトラブルは、おそらく私のWSL2環境特有の現象なので他環境では起きないかと思われますが、アクセスできない時はURLを変更できるというのを頭の片隅に置いておいてもらえればと思います。

wp-contentと指定したディレクトリを紐づける

ローカルで動かすならローカルでファイルを触れるようにしたいものです。

PlaygroundのWordPressを特定のディレクトリと紐づける --mount オプションを追加して起動してみます。

npx @wp-playground/cli@latest start --mount=./my-content:/wordpress/wp-content --site-url=http://localhost:9400

起動ログは下記のように表示されました。

Site files stored at: /home/hoge/.wordpress-playground/sites/0f47879d36b338f9d0363c028b63f38e67e8d8585242e436c604887b2ff62ce5

WordPress Playground CLI

PHP 8.3  WordPress latest
Extensions intl
Mount ./my-content → /wordpress/wp-content
Mount /home/hoge/.wordpress-playground/sites/0f47879d36b338f9d0363c028b63f38e67e8d8585242e436c604887b2ff62ce5 → /wordpress

Logging in 100%

二つのマウントが確認できました。

Mount ./my-content → /wordpress/wp-content
Mount ~/.wordpress-playground/sites/<hash> → /wordpress

WordPressコア本体は引き続き ~/.wordpress-playground/sites/... 側（/wordpress全体にマウント）で、その中の wp-content だけが ./my-content（カレントディレクトリ側）で上書きされている、という二層構造になっているようです。

SQLiteのDBファイルも my-content ディレクトリ内に作られています。

./my-content/database/.ht.sqlite

ちなみにこの状態でブラウザで確認すると、WordPressのインストール画面になります。

先ほど起動したWordPressとは別のDBと接続しているためです。（ちなみにオプションなしで起動すると自動インストール＆ログインという処理が走るようです）

インストールは普通にできたのですが、「エラー: テーマディレクトリ "twentytwentyfive" が存在しません。」というエラーが発生します。
なぜなら、wp-content と紐づいている my-contentフォルダにはデフォルトテーマが入っていないためです。それ以前に themes フォルダがないのでした。
themesフォルダを作って何かしらテーマを追加すればエラーは解消します。

phpMyAdminオプションを付けて起動する

phpMyAdminを指定のフォルダと紐づけた状態で起動をします。まず pma-cache フォルダを作って、--phpmyadmin --mount=./pma-cache:/tools/phpmyadmin オプションを追加して起動します。

mkdir pma-cache
npx @wp-playground/cli@latest start --mount=./my-content:/wordpress/wp-content --site-url=http://localhost:9400 --phpmyadmin --mount=./pma-cache:/tools/phpmyadmin

3種類のマウントをした状態で起動されました

WordPress Playground CLI

PHP 8.3  WordPress latest
Extensions intl
Mount ./my-content → /wordpress/wp-content
Mount ./pma-cache → /tools/phpmyadmin
Mount /home/hoge/.wordpress-playground/sites/0f47879d36b338f9d0363c028b63f38e67e8d8585242e436c604887b2ff62ce5 → /wordpress

Logging in 100%

Ready! WordPress is running on <http://127.0.0.1:9400> (6 workers)

phpMyAdmin available at <http://127.0.0.1:9400/phpmyadmin/index.php?route=/database/structure&db=wordpress>

下記URLにアクセスするとphpMyAdminの画面が表示されました。

<http://localhost:9400/phpmyadmin/index.php?route=/database/structure&db=wordpress>

Blueprintを作成＆指定して起動する

Playgorund環境の初期化設定ができるBlueprintを作成＆指定して起動してみます。

先ほどまで作業していたディレクトリとは別のBlueprint検証用のディレクトリ /home/hoge/projects/playground-cli-demo-blueprint を作成して、ここで作業をします。

作業ディレクトリにBlueprintのファイル my-blueprint.json を作成します。

{
  "$schema": "<https://playground.wordpress.net/blueprint-schema.json>",
  "landingPage": "/wp-admin/",
  "login": true,
  "siteOptions": {
    "blogname": "Blueprint検証サイト"
  },
  "steps": [
    {
      "step": "installTheme",
      "themeData": {
        "resource": "wordpress.org/themes",
        "slug": "twentytwentyfour"
      },
      "options": {
        "activate": true
      }
    },
    {
      "step": "runPHP",
      "code": "<?php require_once '/wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'Blueprintから自動生成された投稿', 'post_content' => '<!-- wp:paragraph --><p>これはBlueprintのrunPHPステップで作成された投稿です。</p><!-- /wp:paragraph -->', 'post_status' => 'publish', 'post_author' => 1)); ?>"
    }
  ]
}

何となく推測できますが、このBlueprintは下記処理の指定をしています。

• 起動したら管理画面を表示

• ログイン済みにする

• ブログ名は「Blueprint検証サイト」にする

• installThemeステップで、wordpress.org公式テーマ(twentytwentyfour)を自動ダウンロード・有効化

• runPHPステップで、任意のPHPコード(wp_insert_post)を実行し、投稿データまで自動生成

Blueprintのファイルを指定して起動してみます。

npx @wp-playground/cli@latest start --blueprint=./my-blueprint.json --site-url=http://localhost:9401 --port=9401

起動ログは下記になります。

$ npx @wp-playground/cli@latest start --blueprint=./my-blueprint.json --site-url=http://localhost:9400
Site files stored at: /home/hoge/.wordpress-playground/sites/4f0ebb0f5ec5b29ad04b4c6f6c0b25eb91636f89700e10d79960863ab60bfe3e

WordPress Playground CLI

PHP 8.3  WordPress latest
Extensions intl
Mount /home/hoge/.wordpress-playground/sites/4f0ebb0f5ec5b29ad04b4c6f6c0b25eb91636f89700e10d79960863ab60bfe3e → /wordpress
Blueprint ./my-blueprint.json

Activating twentytwentyfour 100%

Ready! WordPress is running on <http://127.0.0.1:9400> (6 workers)

起動ログの内容を確認してみましょう。

ディレクトリを変えたことで、WordPress Playgroundで使用するディレクトリが新しく作られました。（ハッシュ値が別になっています）

今回: 4f0ebb0f5ec5b29ad04b4c6f6c0b25eb91636f89700e10d79960863ab60bfe3e
先回: 0f47879d36b338f9d0363c028b63f38e67e8d8585242e436c604887b2ff62ce5

ディレクトリによって保存先が変わるのがわかります。

ブラウザで http://localhost:9400/ にアクセスすると、WordPressが表示されます。
Blueprintに書かれた通り、テーマがTwentyTwentyFourになっていて、自動生成された記事が追加されています。

まとめ

WordPress Playground CLIはNode.js環境があればnpxコマンド一発でWordPress環境が立ち上がり、ローカルのフォルダと連携できることで手元でファイルの追加編集ができる、手軽さと使いやすさを併せ持つツールでした。

Web版同様の仕組みなので、DBがSQLite、一部プラグインの制限等がありますが、純粋なテーマ制作・簡単なプラグイン開発ならこれでいけそうな気もしてきました。（実案件はいろいろ要望・制限あるのでなかなか難しそうですが）

今回ざっとオプション付き・Blueprint指定で起動してみましたが、他にも沢山の機能や設定があるので、まだまだ奥が深そうです。

必要に応じて開発ツールは選んで柔軟に対応していきたいですね。