blueprint

WordPress Playground ブループリント

概要

ブループリントは、WordPress Playground のインスタンスを宣言的に設定する JSON ファイルです。プラグインやテーマのインストール、オプションの設定、PHP／SQL の実行、ファイルの操作などを行います。

基本原則： ブループリントは、信頼できる JSON のみの宣言です。任意の JavaScript は使用しません。ウェブ、Node.js、CLI で動作します。

クイックスタートテンプレート

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [{ "step": "login" }]
}

トップレベルのプロパティ

すべて任意です。ドキュメントに記載されたキーのみ使用できます。スキーマは不明なプロパティを拒否します。

プロパティ	型	備考
$schema	string	常に "https://playground.wordpress.net/blueprint-schema.json" です
landingPage	string	相対パス。例：/wp-admin/
description	string	非推奨の任意のトップレベル説明です。新しいブループリントでは meta.description を使用してください
meta	object	{ title, author, description?, categories? } — title と author は必須です
preferredVersions	object	{ php, wp } — 指定する場合は両方必須です
features	object	{ networking?: boolean, intl?: boolean } — この 2 つのキーのみ指定できます。Networking の既定値は true です
phpExtensionBundles	any	非推奨／現在は使用されていません。スキーマでは値に制約を設けておらず、ブループリントから削除するよう定めています
extraLibraries	array	["wp-cli"] — wp-cli ステップがある場合に自動的に含まれます
constants	object	defineWpConfigConsts の簡易記法です。値は string／boolean／number です
plugins	array	installPlugin ステップの簡易記法です。文字列は wp.org のスラッグを表します
siteOptions	object	setSiteOptions の簡易記法です
login	boolean or object	true = 管理者としてログインします。オブジェクト = { username?, password? }（どちらも既定値は "admin"／"password"）
steps	array	メインの実行パイプラインです。簡易記法の後に実行されます

preferredVersions の値

• php： メジャー・マイナーのみです。"7.4"、"8.0"、"8.1"、"8.2"、"8.3"、"8.4"、"8.5"、または "latest" を指定します。"7.4.1" のようなパッチバージョンは無効です。現在サポートされているバージョンはスキーマで確認してください。
• wp： 最近のメジャーバージョン、"latest"、"beta"、"nightly"／"trunk"、またはカスタム zip の URL を指定します。スキーマでは、PHP のみの Playground を使用するための false も受け付けます。wp: false と plugins、siteOptions、login などの WordPress 専用フィールドや、WordPress 専用ステップを併用しないでください。

簡易記法とステップ

簡易記法（login、plugins、siteOptions、constants）は展開され、順序は指定されずに steps の前に追加されます。実行順序が重要な場合は、明示的なステップを使用してください。

リソース参照

リソースは、ファイルの場所を Playground に伝えます。installPlugin、installTheme、writeFile、writeFiles、importWxr などで使用します。

リソースの種類	必須フィールド	例
wordpress.org/plugins	slug	{ "resource": "wordpress.org/plugins", "slug": "woocommerce" }
wordpress.org/themes	slug	{ "resource": "wordpress.org/themes", "slug": "astra" }
url	url	{ "resource": "url", "url": "https://example.com/plugin.zip" }
git:directory	url、ref	以下を参照
literal	name、contents	{ "resource": "literal", "name": "file.txt", "contents": "hello" }
literal:directory	name、files	以下を参照
bundled	path	ブループリントバンドル内のファイルを参照します（例：{ "resource": "bundled", "path": "/plugin.zip" }）
zip	inner	別のリソースを ZIP でラップします。ソースが ZIP ではないのにステップで ZIP が必要な場合に使用します（例：生のディレクトリを指す url リソースをラップする）

git:directory — GitHub からのインストール

{
  "resource": "git:directory",
  "url": "https://github.com/WordPress/gutenberg",
  "ref": "trunk",
  "refType": "branch",
  "path": "/"
}

• ブランチ名またはタグ名を ref に指定する場合は、refType（"branch" | "tag" | "commit" | "refname"）を必ず設定してください。設定しない場合、確実に解決されるのは "HEAD" のみです。
• path はサブディレクトリを選択します（既定値はリポジトリのルートです）。

literal:directory — インラインファイルツリー

{
  "resource": "literal:directory",
  "name": "my-plugin",
  "files": {
    "plugin.php": "<?php /* Plugin Name: My Plugin */ ?>",
    "includes": {
      "helper.php": "<?php // helper code ?>"
    }
  }
}

• files では、サブディレクトリを表すためにネストされたオブジェクトを使います。キーはファイル名またはディレクトリ名、値はプレーン文字列（ファイルの内容）またはオブジェクト（サブディレクトリ）です。値としてリソース参照を使わないでください。
• キーにパス区切り文字を使わないでください（例："includes/helper.php"は誤りです。ネストした"includes": { "helper.php": "..." }オブジェクトを使ってください）。

ステップのリファレンス

すべてのステップで"step": "<name>"が必要です。UI フィードバック用に、任意のステップに"progress": { "weight": 1, "caption": "Installing..." }を含めることができます。

プラグインとテーマのインストール

{
  "step": "installPlugin",
  "pluginData": { "resource": "wordpress.org/plugins", "slug": "gutenberg" },
  "options": { "activate": true, "targetFolderName": "gutenberg" },
  "ifAlreadyInstalled": "overwrite"
}

{
  "step": "installTheme",
  "themeData": { "resource": "wordpress.org/themes", "slug": "twentytwentyfour" },
  "options": { "activate": true, "importStarterContent": true },
  "ifAlreadyInstalled": "overwrite"
}

• 非推奨のpluginZipFile / themeZipFileではなく、pluginData / themeDataを使います。
• pluginData / themeDataでは、任意のFileReferenceまたはDirectoryReferenceを使用できます。zip URL、wordpress.org/pluginsスラッグ、git:directory、literal:directoryなどです（zipラッパーは不要です）。
• options.activateで有効化を制御します。installPlugin / installThemeを使う場合、別途activatePlugin / activateThemeステップを実行する必要はありません。
• ifAlreadyInstalled："overwrite" | "skip" | "error"

有効化（単独）

すでにディスク上にあるプラグインやテーマ（例：writeFile / writeFilesの後）の場合にのみ必要です。

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

{ "step": "activateTheme", "themeFolderName": "twentytwentyfour" }

ファイル操作

{ "step": "writeFile", "path": "/wordpress/wp-content/mu-plugins/custom.php", "data": "<?php // code" }

dataには、プレーン文字列（上記の例）またはリソース参照（例：{ "resource": "url", "url": "https://..." }）を指定できます。

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/",
      "includes": {
        "helpers.php": "<?php // helpers"
      }
    }
  }
}

writeFilesのfilesTreeにはDirectoryReference（literal:directoryまたはgit:directory）が必要です。プレーンオブジェクトは指定できません。

その他のファイル操作：mkdir、cp、mv、rm、rmdir、unzip。

コードの実行

runPHP：

{ "step": "runPHP", "code": "<?php require '/wordpress/wp-load.php'; update_option('key', 'value');" }

注意： WordPressの関数を使うには、require '/wordpress/wp-load.php';が必要です。

wp-cli：

{ "step": "wp-cli", "command": "wp post create --post_type=page --post_title='Hello' --post_status=publish" }

ステップ名はcliやwpcliではなく、ハイフンを含むwp-cliです。

runSql：

{ "step": "runSql", "sql": { "resource": "literal", "name": "q.sql", "contents": "UPDATE wp_options SET option_value='val' WHERE option_name='key';" } }

サイト設定

{ "step": "setSiteOptions", "options": { "blogname": "My Site", "blogdescription": "A tagline" } }

{ "step": "defineWpConfigConsts", "consts": { "WP_DEBUG": true } }

{ "step": "setSiteLanguage", "language": "en_US" }

{ "step": "defineSiteUrl", "siteUrl": "https://example.com" }

その他のステップ

ステップ	主なプロパティ
login	username?、password?（デフォルトは"admin" / "password"）
enableMultisite	（必須プロパティなし）
importWxr	file（FileReference）
importThemeStarterContent	themeSlug?
importWordPressFiles	wordPressFilesZip、pathInZip? — zipからWordPressのディレクトリ全体をインポートします
request	request: { url, method?, headers?, body? }
updateUserMeta	userId、meta
runWpInstallationWizard	options? — 指定したオプションでWPインストールウィザードを実行します
resetData	（プロパティなし）

よくあるパターン

インラインmu-plugin（手軽なカスタムコード）

{
  "step": "writeFile",
  "path": "/wordpress/wp-content/mu-plugins/custom.php",
  "data": "<?php\n// mu-plugins load automatically — no activation needed, no require wp-load.php\nadd_filter('show_admin_bar', '__return_false');"
}

複数ファイルを含むインラインプラグイン

{
  "step": "writeFiles",
  "writeToPath": "/wordpress/wp-content/plugins/",
  "filesTree": {
    "resource": "literal:directory",
    "name": "my-plugin",
    "files": {
      "my-plugin.php": "<?php\n/*\nPlugin Name: My Plugin\n*/\nrequire __DIR__ . '/includes/main.php';",
      "includes": {
        "main.php": "<?php // main logic"
      }
    }
  }
}

その後、別のステップで有効化します。

{ "step": "activatePlugin", "pluginPath": "my-plugin/my-plugin.php" }

GitHubブランチからのプラグイン

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "git:directory",
    "url": "https://github.com/user/repo",
    "ref": "feature-branch",
    "refType": "branch",
    "path": "/"
  }
}

よくある間違い

間違い	正しい方法
pluginZipFile / themeZipFile	pluginData / themeData
"step": "cli"	"step": "wp-cli"
writeFiles.filesTreeにフラットなオブジェクトを指定	literal:directoryまたはgit:directoryリソースを指定する必要があります
filesキーにパス区切り文字を使用	サブディレクトリにはネストされたオブジェクトを使います
wp-load.phpを使わずにrunPHPを実行	WP関数を使う場合は必ずrequire '/wordpress/wp-load.php';を指定します
トップレベルのキーを独自に追加	ドキュメントに記載されたキーのみ使用できます。スキーマが不明なプロパティを拒否します
GitHub用のプロキシURLを独自に作成	git:directoryリソースタイプを使います
ブランチまたはタグのrefにrefTypeを指定しない	必須です。指定しない場合に使えるのは"HEAD"のみです
literal:directoryのfiles値にリソース参照を指定	値はプレーン文字列（内容）またはオブジェクト（サブディレクトリ）である必要があります。リソース参照は使わないでください
features.debugなどの機能キーを独自に追加	featuresがサポートするのはnetworkingとintlのみです。デバッグモードにはconstants: { "WP_DEBUG": true }を使います
mu-pluginコードでrequire wp-load.phpを指定	runPHPステップでのみ必要です。mu-pluginはすでにWordPress内で実行されます
.orgドメインのスキーマURL	playground.wordpress.orgではなく、playground.wordpress.netである必要があります

完全リファレンス

このスキルでは、よく使われる手順やパターンを紹介します。API の全容については、以下をご覧ください。

• Blueprint のドキュメント： https://wordpress.github.io/wordpress-playground/blueprints
• JSON スキーマ： https://playground.wordpress.net/blueprint-schema.json

上記で扱っていない追加のステップは、runPHPWithOptions（カスタムの ini 設定で PHP を実行）、runWpInstallationWizard、およびリソースタイプの vfs と bundled（高度な埋め込みシナリオ向け）です。

Blueprint バンドル

バンドルは、blueprint.json とそれが参照するすべてのリソース（プラグイン、テーマ、WXR ファイルなど）を含む、自己完結型のパッケージです。アセットを外部でホストする代わりに、Blueprint と一緒にまとめてください。

バンドルの構成

my-bundle/
├── blueprint.json          ← must be at the root
├── my-plugin.zip           ← zipped plugin directory
├── theme.zip
└── content/
    └── sample-content.wxr

プラグインとテーマは、バンドルする前に ZIP 形式にする必要があります。installPlugin が受け付けるのは ZIP ファイルであり、展開済みのディレクトリではありません。プラグインディレクトリから ZIP ファイルを作成するには、次のようにします。

cd my-bundle
zip -r my-plugin.zip my-plugin/

バンドルされたリソースの参照

bundled リソースタイプを使って、バンドル内のファイルを参照します。

{
  "step": "installPlugin",
  "pluginData": {
    "resource": "bundled",
    "path": "/my-plugin.zip"
  },
  "options": { "activate": true }
}

{
  "step": "importWxr",
  "file": {
    "resource": "bundled",
    "path": "/content/sample-content.wxr"
  }
}

バンドルの作成手順

1. バンドルディレクトリを作成し、そのルートに blueprint.json を追加します。
2. プラグイン／テーマのソースファイルをサブディレクトリに作成します（例：my-plugin/my-plugin.php）。
3. プラグインディレクトリを ZIP 形式にします：zip -r my-plugin.zip my-plugin/
4. { "resource": "bundled", "path": "/my-plugin.zip" } を使って、blueprint.json から参照します。

完全な例 — カスタムプラグインをインストールするバンドル：

dashboard-widget-bundle/
├── blueprint.json
├── dashboard-widget.zip        ← zip of dashboard-widget/
└── dashboard-widget/           ← plugin source (kept for editing)
    └── dashboard-widget.php

{
  "$schema": "https://playground.wordpress.net/blueprint-schema.json",
  "landingPage": "/wp-admin/",
  "preferredVersions": { "php": "8.3", "wp": "latest" },
  "steps": [
    { "step": "login" },
    {
      "step": "installPlugin",
      "pluginData": { "resource": "bundled", "path": "/dashboard-widget.zip" },
      "options": { "activate": true }
    }
  ]
}

配布形式

形式	使用方法
ZIP ファイル（リモート）	Web サイト：https://playground.wordpress.net/?blueprint-url=https://example.com/bundle.zip
ZIP ファイル（ローカル）	CLI：npx @wp-playground/cli server --blueprint=./bundle.zip
ローカルディレクトリ	CLI：npx @wp-playground/cli server --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files
Git リポジトリのディレクトリ	blueprint.json を含むリポジトリディレクトリを blueprint-url に指定します

注意点： ローカルディレクトリのバンドルから CLI がバンドル内のリソースを読み取るには、必ず --blueprint-may-read-adjacent-files が必要です。このフラグがないと、"resource": "bundled" を参照するものはすべて「File not found」エラーになります。ZIP バンドルにはこのフラグは不要です。すべてのファイルがアーカイブ内に含まれているためです。

Blueprint のテスト

インライン Blueprint（手早くテスト、バンドル不要）

Blueprint の JSON を最小化し（余分な空白を削除）、encodeURIComponent() で一度エンコードしてから、先頭に https://playground.wordpress.net/# を付け、ブラウザーで URL を開きます。

https://playground.wordpress.net/#%7B%22%24schema%22%3A%22https%3A%2F%2Fplayground.wordpress.net%2Fblueprint-schema.json%22%2C%22preferredVersions%22%3A%7B%22php%22%3A%228.3%22%2C%22wp%22%3A%22latest%22%7D%2C%22steps%22%3A%5B%7B%22step%22%3A%22login%22%7D%5D%7D

非常に大きな Blueprint はブラウザーの URL 長制限を超えることがあります。その場合は CLI を使うか、ホストされた Blueprint URL を使用してください。共有リンクの詳細については、wp-playground/references/website.md をご覧ください。

ローカル CLI でのテスト

対話型サーバー（実行を続け、ブラウザーで開きます）：

# Directory bundle — requires --blueprint-may-read-adjacent-files
npx @wp-playground/cli server --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files

# ZIP bundle — self-contained, no extra flags needed
npx @wp-playground/cli server --blueprint=./bundle.zip

ヘッドレス検証（Blueprint を実行して終了します）：

npx @wp-playground/cli run-blueprint --blueprint=./my-bundle/ --blueprint-may-read-adjacent-files

WordPress Playground でのテスト

ローカルまたはブラウザーでのテストには、wp-playground スキルを使います。CLI でテストする場合は、--blueprint=<path-or-url> を指定して wp-playground/references/cli.md の手順に従ってください。ディレクトリバンドルの場合は、--blueprint-may-read-adjacent-files を渡します。