WordPress Playground

https://wordpress.github.io/wordpress-playground
Admin
WordPress Playground is an online platform that lets you run WordPress instantly in your browser...
Tokens:524,671
Snippets:3,859
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install WordPress Theme Example

Source: https://wordpress.github.io/wordpress-playground/api/blueprints/interface/InstallThemeStep

Demonstrates how to install a WordPress theme using the 'installTheme' step. It specifies the theme source, slug, and optional settings like activation and starter content import. This example assumes the necessary WordPress Playground environment is set up.

```json
{
  "step": "installTheme",
  "themeData": {
    "resource": "wordpress.org/themes",
    "slug": "pendant"
  },
  "options": {
    "activate": true,
    "importStarterContent": true
  }
}
```

--------------------------------

### Install Plugin from WordPress.org

Source: https://wordpress.github.io/wordpress-playground/api/blueprints/interface/InstallPluginStep

Installs a plugin from wordpress.org and activates it. This example demonstrates installing the 'gutenberg' plugin. It requires the 'wordpress.org/plugins' resource type and the plugin's slug.

```json
{
    "step": "installPlugin",
    "pluginData": {
        "resource": "wordpress.org/plugins",
        "slug": "gutenberg"
    },
    "options": {
        "activate": true
    }
}
```

--------------------------------

### Set Up Local Gutenberg Development Environment

Source: https://wordpress.github.io/wordpress-playground/contributing/contributor-day

This snippet details the initial setup for contributing to the Gutenberg project. It involves cloning the repository, installing Node.js dependencies, and starting a local development server. This is essential for making and testing code changes.

```bash
git clone git@github.com:WordPress/gutenberg.git
cd gutenberg
npm install
npm run dev
```

```bash
cd gutenberg
npx @wp-playground/cli@latest server --auto-mount
```

--------------------------------

### JavaScript API - Quick Start

Source: https://wordpress.github.io/wordpress-playground/developers/apis/javascript-api

This example demonstrates the basic setup for using the WordPress Playground JavaScript API by initializing a client within an iframe.

```APIDOC
## JavaScript API - Quick Start

### Description
This section provides the shortest example of how to use the JavaScript API in an HTML page. It involves setting up an iframe and initializing the Playground client.

### Method
Initialization via JavaScript function call.

### Endpoint
N/A (Client-side JavaScript)

### Parameters
#### Request Body
- **iframe** (HTMLIFrameElement) - Required - The iframe element where the Playground will be rendered.
- **remoteUrl** (string) - Required - The URL to the remote Playground API endpoint (e.g., `/remote.html`).

### Request Example
```html
<iframe  
	id="wp"
	style="width: 100%; height: 300px; border: 1px solid #000;"
></iframe>
<script type="module">
	// Use unpkg for convenience
	import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';

	const client = await startPlaygroundWeb({
		iframe: document.getElementById('wp'),
		remoteUrl: `https://playground.wordpress.net/remote.html`,
	});
	// Let's wait until Playground is fully loaded
	await client.isReady();
</script>
```

### Response
#### Success Response (Initialization)
- **client** (object) - An instance of the Playground client object, used to interact with the WordPress instance.

#### Response Example
```json
// client object is returned upon successful initialization
{
  "client": "[Playground Client Instance]"
}
```
```

--------------------------------

### Install Custom Plugin, Theme, and Import Content (JSON Blueprints)

Source: https://wordpress.github.io/wordpress-playground/developers/build-your-first-app

Showcases how to use JSON Blueprints to install a custom plugin and theme from a URL, and import starter content (WXR file). This provides a high degree of control over the embedded WordPress instance.

```json
{
	"steps": [
		{
			"step": "installPlugin",
			"pluginData": {
				"resource": "url",
				"url": "https://your-site.com/your-plugin.zip"
			}
		},
		{
			"step": "installTheme",
			"themeData": {
				"resource": "url",
				"url": "https://your-site.com/your-theme.zip"
			}
		},
		{
			"step": "importWxr",
			"file": {
				"resource": "url",
				"url": "https://your-site.com/starter-content.wxr"
			}
		}
	]
}
```

--------------------------------

### Install Plugin from Git Repository

Source: https://wordpress.github.io/wordpress-playground/api/blueprints/interface/InstallPluginStep

Installs a plugin from a Git repository and activates it. This example shows how to install the 'hello-dolly' plugin from a specific GitHub repository and path. It requires the Git URL, reference, and the path to the plugin within the repository.

```json
{
    "step": "installPlugin",
    "pluginData": {
        "resource": "git:directory",
        "url": "https://github.com/wordpress/wordpress-playground.git",
        "ref": "HEAD",
        "path": "wp-content/plugins/hello-dolly"
    },
    "options": {
        "activate": true
    }
}
```

--------------------------------

### Start Playground CLI Server

Source: https://wordpress.github.io/wordpress-playground/developers/local-development/wp-playground-cli

Starts a fresh WordPress instance using the Playground CLI. This is the most basic command to get a test environment running.

```bash
npx @wp-playground/cli@latest server
```

--------------------------------

### Example Blueprint JSON Configuration

Source: https://wordpress.github.io/wordpress-playground/blueprints/getting-started

This is a basic example of a Blueprint JSON file. It defines the schema, landing page, preferred PHP and WordPress versions, and a login step with username and password. This structure allows for declarative configuration of a WordPress Playground environment.

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

--------------------------------

### JavaScript API with Blueprints

Source: https://wordpress.github.io/wordpress-playground/fr/blueprints/using-blueprints

This example demonstrates how to initialize the WordPress Playground using the `startPlaygroundWeb` function and configure it with a Blueprint. The Blueprint defines initial setup steps like landing page, PHP and WordPress versions, user login, and plugin installation. It also shows how to execute PHP code within the playground and log the response.

```APIDOC
## JavaScript API with Blueprints

### Description
Initialize and control a WordPress Playground instance using the JavaScript API. This example shows how to use `startPlaygroundWeb` with a Blueprint to configure the playground environment, including setting the landing page, preferred versions, user credentials, and installing plugins. It also demonstrates running custom PHP code within the playground and retrieving the output.

### Method
`startPlaygroundWeb(options)`

### Endpoint
N/A (Client-side JavaScript API)

### Parameters
#### Options Object
- **iframe** (HTMLIFrameElement) - Required - The iframe element where the playground will be mounted.
- **remoteUrl** (string) - Required - The URL of the remote playground HTML file.
- **blueprint** (object) - Optional - Configuration for setting up the playground environment.
  - **landingPage** (string) - Optional - The default page to load in the playground (e.g., `/wp-admin/`).
  - **preferredVersions** (object) - Optional - Specifies preferred versions for PHP and WordPress.
    - **php** (string) - Optional - The preferred PHP version (e.g., '8.3').
    - **wp** (string) - Optional - The preferred WordPress version (e.g., 'latest').
  - **steps** (array) - Optional - An array of steps to execute during playground initialization.
    - **step** (string) - Required - The type of step (e.g., 'login', 'installPlugin').
    - **username** (string) - Required for 'login' step - The username for login.
    - **password** (string) - Required for 'login' step - The password for login.
    - **pluginData** (object) - Required for 'installPlugin' step - Data for the plugin to install.
      - **resource** (string) - Required - The resource type (e.g., 'wordpress.org/plugins').
      - **slug** (string) - Required - The plugin slug (e.g., 'friends').

### Request Example (JavaScript Code)
```javascript
<iframe id="wp-playground" style="width: 1200px; height: 800px"></iframe>  
<script type="module">
	import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';  
  
	const client = await startPlaygroundWeb({
		iframe: document.getElementById('wp-playground'),  
		remoteUrl: `https://playground.wordpress.net/remote.html`,
		blueprint: {
			landingPage: '/wp-admin/',  
			preferredVersions: {
				php: '8.3',
				wp: 'latest',
			},
			steps: [
				{
					step: 'login',
					username: 'admin',
					password: 'password',
				},
				{
					step: 'installPlugin',
					pluginData: {
						resource: 'wordpress.org/plugins',
						slug: 'friends',
					},
				},
			],
		},
	});

	const response = await client.run({
		code: '<?php require_once "/wordpress/wp-load.php"; $posts = get_posts(); echo "Post Title: " . $posts[0]->post_title;
';
	});
	console.log(response.text);
</script>
```

### Response
#### Success Response (from `client.run()`)
- **text** (string) - The output of the executed PHP code.

#### Response Example (from `console.log(response.text)`)
```
Post Title: [Your First Post Title]
```
```

--------------------------------

### Install Hello Dolly Plugin using installPlugin Step

Source: https://wordpress.github.io/wordpress-playground/blueprints/tutorial/build-your-first-blueprint

The 'installPlugin' step installs a plugin from a specified resource. This example installs the 'hello-dolly' plugin from the WordPress plugin directory using 'wordpress.org/plugins' resource.

```json
{
	"siteOptions": {
		"blogname": "My first Blueprint"
	},
	"steps": [
		{
			"step": "installTheme",
			"themeData": {
				"resource": "wordpress.org/themes",
				"slug": "adventurer"
			}
		},
		{
			"step": "installPlugin",
			"pluginData": {
				"resource": "wordpress.org/plugins",
				"slug": "hello-dolly"
			}
		}
	]
}
```

--------------------------------

### Example WP-CLI Server Command with Mounted Site and Blueprint

Source: https://wordpress.github.io/wordpress-playground/blueprints/troubleshoot-and-debug

This example demonstrates how to run a local WordPress Playground server with a mounted directory and a specified blueprint. It includes steps to create a directory, save the blueprint, start the server, navigate into the mounted directory, and execute a WP-CLI command.

```bash
mkdir wordpress
# Ensure your blueprint with the above steps is saved as, for example, './blueprint.json'  
npx @wp-playground/cli server --mount-before-install=wordpress:/wordpress --blueprint=./blueprint.json  
cd wordpress  
wp post list  
```

--------------------------------

### Install and Activate Plugins with plugins Shorthand

Source: https://wordpress.github.io/wordpress-playground/bn/guides/for-theme-developers

The `plugins` shorthand provides a concise way to specify a list of plugins to be installed and activated along with a theme in the Playground instance. This example lists two plugins: `todo-list-block` and `markdown-comment-block`.

```json
"plugins": ["todo-list-block", "markdown-comment-block"]
```

--------------------------------

### Example blueprint.json with Bundled Resources

Source: https://wordpress.github.io/wordpress-playground/blueprints/bundles

This JSON example defines a Blueprint configuration that references bundled resources. It includes steps to write a file, install a theme, install a plugin, and import WXR content, all from resources included within the bundle.

```json
{
	"landingPage": "/my-file.txt",
	"steps": [
		{
			"step": "writeFile",
			"path": "/wordpress/my-file.txt",
			"data": {
				"resource": "bundled",
				"path": "/bundled-text-file.txt"
			}
		},
		{
			"step": "installTheme",
			"themeData": {
				"resource": "bundled",
				"path": "/theme.zip"
			}
		},
		{
			"step": "installPlugin",
			"pluginData": {
				"resource": "bundled",
				"path": "/plugin.zip"
			}
		},
		{
			"step": "importWxr",
			"file": {
				"resource": "bundled",
				"path": "/content/sample-content.wxr"
			}
		}
	]
}
```

--------------------------------

### Install Adventurer Theme using installTheme Step

Source: https://wordpress.github.io/wordpress-playground/blueprints/tutorial/build-your-first-blueprint

The 'installTheme' step installs a theme from a specified resource. This example installs the 'adventurer' theme from the WordPress theme directory using 'wordpress.org/themes' resource.

```json
{
	"siteOptions": {
		"blogname": "My first Blueprint"
	},
	"steps": [
		{
			"step": "installTheme",
			"themeData": {
				"resource": "wordpress.org/themes",
				"slug": "adventurer"
			}
		}
	]
}
```

--------------------------------

### Preview Gutenberg PR using Blueprints API

Source: https://wordpress.github.io/wordpress-playground/gu/developers/build-your-first-app

This example demonstrates a comprehensive Blueprint to download, extract, and install a specific Gutenberg pull request artifact.

```APIDOC
## POST /blueprints

### Description
Automates the process of downloading a specific Gutenberg PR artifact, extracting it, and installing it as a plugin within the WordPress Playground environment.

### Method
POST

### Endpoint
/blueprints

### Parameters
#### Request Body
- **landingPage** (string) - Optional - The landing page to navigate to after the steps are completed.
- **steps** (array) - Required - An array of steps to execute.
  - **step** (string) - Required - The type of step to perform (e.g., `login`, `mkdir`, `writeFile`, `unzip`, `installPlugin`).
  - **username** (string) - Required for `login` step - The username for login.
  - **password** (string) - Required for `login` step - The password for login.
  - **path** (string) - Required for `mkdir` and `writeFile` steps - The path for directory creation or file writing.
  - **data** (object) - Required for `writeFile` step - Data to write to the file.
    - **resource** (string) - Required - Must be `url`.
    - **url** (string) - Required - The URL to download the data from.
    - **caption** (string) - Optional - A caption for the download progress.
  - **zipPath** (string) - Required for `unzip` step - The path to the zip file.
  - **extractToPath** (string) - Required for `unzip` step - The path to extract the contents to.
  - **pluginData** (object) - Required for `installPlugin` step - Data for plugin installation.
    - **resource** (string) - Required - Must be `vfs`.
    - **path** (string) - Required - The path to the plugin directory or zip file within the virtual file system.
  - **progress** (object) - Optional - Progress information for a step.
    - **weight** (number) - Optional - The weight of the progress step.
    - **caption** (string) - Optional - A caption to display for the progress.

### Request Example
```json
{
  "landingPage": "/wp-admin/plugins.php?test=42test",
  "steps": [
    {
      "step": "login",
      "username": "admin",
      "password": "password"
    },
    {
      "step": "mkdir",
      "path": "/wordpress/pr"
    },
    {
      "step": "writeFile",
      "path": "/wordpress/pr/pr.zip",
      "data": {
        "resource": "url",
        "url": "/plugin-proxy.php?org=WordPress&repo=gutenberg&workflow=Build%20Gutenberg%20Plugin%20Zip&artifact=gutenberg-plugin&pr=60819",
        "caption": "Downloading Gutenberg PR 47739"
      },
      "progress": {
        "weight": 2,
        "caption": "Applying Gutenberg PR 47739"
      }
    },
    {
      "step": "unzip",
      "zipPath": "/wordpress/pr/pr.zip",
      "extractToPath": "/wordpress/pr"
    },
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "vfs",
        "path": "/wordpress/pr/gutenberg.zip"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message** (string) - A message describing the result of the operation.
```

--------------------------------

### Preview Pull Requests using Zip URL

Source: https://wordpress.github.io/wordpress-playground/tl/developers/build-your-first-app

This section explains how to preview pull requests by loading a `.zip` file from a URL using WordPress Playground Blueprints.

```APIDOC
## POST /blueprints

### Description
Installs a plugin from a specified `.zip` file URL using the `url` resource within WordPress Playground Blueprints.

### Method
POST

### Endpoint
/blueprints

### Parameters
#### Request Body
- **steps** (array) - Required - An array of steps to execute.
  - **step** (string) - Required - The name of the step, must be `installPlugin`.
  - **pluginData** (object) - Required - Data for the plugin installation.
    - **resource** (string) - Required - The resource type, must be `url`.
    - **url** (string) - Required - The URL of the `.zip` file.

### Request Example
```json
{
  "steps": [
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "url",
        "url": "https://your-site.com/pull-request-1234.zip"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Load Blueprint Configuration with Playground CLI

Source: https://wordpress.github.io/wordpress-playground/developers/local-development/wp-playground-cli

Starts the Playground CLI server using a blueprint file to define the initial state of the WordPress instance. This enables pre-configured setups with specific plugins and landing pages.

```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"
  ]
}
```

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

--------------------------------

### Showcase WordPress Plugin from Directory (HTML)

Source: https://wordpress.github.io/wordpress-playground/developers/build-your-first-app

Demonstrates how to embed WordPress Playground and pre-install a specific plugin from the WordPress directory using URL parameters. This utilizes the Query API.

```html
<iframe src="https://playground.wordpress.net/?plugin=coblocks"></iframe>
```

--------------------------------

### Showcase Product Demo with URL Resources in Playground Blueprint

Source: https://wordpress.github.io/wordpress-playground/blueprints/examples

This Blueprint demonstrates installing a plugin, theme, and importing WXR content from URLs, then setting site options. It's useful for showcasing a product demo with pre-defined content and configurations.

```json
{
	"steps": [
		{
			"step": "installPlugin",
			"pluginData": {
				"resource": "url",
				"url": "https://your-site.com/your-plugin.zip"
			}
		},
		{
			"step": "installTheme",
			"themeData": {
				"resource": "url",
				"url": "https://your-site.com/your-theme.zip"
			}
		},
		{
			"step": "importWxr",
			"file": {
				"resource": "url",
				"url": "https://your-site.com/starter-content.wxr"
			}
		},
		{
			"step": "setSiteOptions",
			"options": {
				"some_required_option_1": "your_favorite_values",
				"some_required_option_2": "your_favorite_values"
			}
		}
	]
}
```

--------------------------------

### Run WordPress Playground via @wp-playground/cli

Source: https://wordpress.github.io/wordpress-playground/contributing/contributor-day

This code example demonstrates how to use the `@wp-playground/cli` NPM package to quickly start a local WordPress server from a plugin or theme directory. It requires Node.js and NPM, and streamlines local development without Docker, MySQL, or Apache.

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

--------------------------------

### Quick Start Xdebug with npx

Source: https://wordpress.github.io/wordpress-playground/bn/developers/xdebug/getting-started

This command starts a WordPress server in the playground with Xdebug enabled, allowing for immediate debugging without installation. It's the fastest way to begin debugging PHP code in a WordPress environment.

```bash
npx @wp-playground/cli@latest server --xdebug  

```

--------------------------------

### runWpInstallationWizard

Source: https://wordpress.github.io/wordpress-playground/api/blueprints/function/runWpInstallationWizard

Installs WordPress using the provided PHP instance and arguments. Optionally accepts progress arguments for tracking installation steps.

```APIDOC
## runWpInstallationWizard

### Description
Installs WordPress using the provided PHP instance and arguments. Optionally accepts progress arguments for tracking installation steps.

### Method
Not specified (likely a function call within a client library)

### Endpoint
Not applicable (function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **php** (UniversalPHP) - Required - A PHP instance or Playground client.
* **args** (Omit<RunWpInstallationWizardStep, step>) - Required - Arguments for running the WordPress installation wizard, excluding the 'step' field.
* **progressArgs** (StepProgress) - Optional - Arguments for tracking the progress of the installation steps.
```

--------------------------------

### WordPress Installation Wizard

Source: https://wordpress.github.io/wordpress-playground/tl/api/blueprints/function/runWpInstallationWizard

Initiates the WordPress installation wizard with specified arguments and optional progress tracking.

```APIDOC
## POST /runWpInstallationWizard

### Description
Installs WordPress by running the installation wizard.

### Method
POST

### Endpoint
/runWpInstallationWizard

### Parameters
#### Request Body
- **php** (UniversalPHP) - Required - A PHP instance or Playground client.
- **args** (Omit<RunWpInstallationWizardStep, step>) - Required - Arguments for the installation steps, excluding the 'step' field.
- **progressArgs** (StepProgress) - Optional - Arguments for tracking the progress of installation steps.

### Request Example
```json
{
  "php": "<php_instance_or_client>",
  "args": {
    "<other_args>": "<value>"
  },
  "progressArgs": {
    "<progress_args>": "<value>"
  }
}
```

### Response
#### Success Response (200)
- **any** - Returns any as the result of the installation process.

#### Response Example
```json
{
  "result": "<installation_result>"
}
```
```

--------------------------------

### Start WordPress Playground Server with Xdebug Enabled

Source: https://wordpress.github.io/wordpress-playground/gu/developers/xdebug/getting-started

This command starts a WordPress server instance within the Playground environment with Xdebug enabled. It's the quickest way to begin debugging without any installation. The server will be accessible at http://127.0.0.1:9400.

```bash
npx @wp-playground/cli@latest server --xdebug
```

--------------------------------

### Start Playground CLI Server with DevTools Debugger

Source: https://wordpress.github.io/wordpress-playground/bn/developers/xdebug/getting-started

This command starts the Playground CLI server with Xdebug enabled and the experimental DevTools debugger flag. It allows you to connect Chrome DevTools to your PHP application for debugging. Ensure you have `@wp-playground/cli` installed.

```bash
npx @wp-playground/cli@latest server --xdebug --experimental-devtools
```

--------------------------------

### Combine Mounting and Blueprint with runCLI

Source: https://wordpress.github.io/wordpress-playground/bn/developers/local-development/wp-playground-cli

Combines mounting a local plugin directory with defining a blueprint to activate the mounted plugin. This example uses `runCLI` to set up a WordPress server, mount a local plugin, and then activate it via the blueprint.

```typescript
  
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);

```

--------------------------------

### Enable Networking and Login in Playground Blueprint

Source: https://wordpress.github.io/wordpress-playground/blueprints/examples

This Blueprint enables the WordPress networking feature and includes a 'login' step, directing the user to the plugin installation page. It's a configuration for multisite setups.

```json
{
	"landingPage": "/wp-admin/plugin-install.php",
	"features": {
		"networking": true
	},
	"steps": [
		{
			"step": "login"
		}
	]
}
```

--------------------------------

### Example WordPress Plugin for DevTools Debugging

Source: https://wordpress.github.io/wordpress-playground/bn/developers/xdebug/getting-started

A simple WordPress plugin that displays a message in the admin area. This code can be used to demonstrate setting breakpoints and stepping through code using the DevTools debugger.

```php
<?php
/**
 * Plugin Name: Simple Admin Message
 * Description: Displays a simple message in the WordPress admin
 * Version: 1.0
 * Author: Playground Team
 */

// Prevent direct access
if (!defined('ABSPATH')) {
    exit;
}

// Display admin notice
function sam_display_admin_message() {
    $message = 'Hello! This is a simple admin message.';
    ?>
    <div class="notice notice-info is-dismissible">
        <p><?php _e($message, 'simple-admin-message'); ?></p>
    </div>
    <?php
}
add_action('admin_notices', 'sam_display_admin_message');

```

--------------------------------

### Configure WordPress Playground with JSON Blueprints

Source: https://wordpress.github.io/wordpress-playground/bn/developers/apis

Defines a WordPress Playground setup using a JSON Blueprint. This example demonstrates logging in, installing the 'friends' plugin, and creating a post using PHP execution.

```json
{
  "steps": [
    {
      "step": "login"
    },
    {
      "step": "installPlugin",
      "pluginData": {
        "resource": "wordpress.org/plugins",
        "slug": "friends"
      }
    },
    {
      "step": "runPHP",
      "code": "<?php require_once '/wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'Post title', 'post_content' => 'Post content', 'post_status' => 'publish', 'post_author' => 1)); ?>"
    }
  ]
}
```

--------------------------------

### Configure Docusaurus for Language Switcher and Build

Source: https://wordpress.github.io/wordpress-playground/contributing/translations

Example of Docusaurus configuration that includes i18n settings and a localeDropdown component for the navigation bar. This setup ensures that translated subsites are generated correctly and the language switcher is displayed.

```json
{
  "i18n": {
    "defaultLocale": "en",
    "path": "i18n",
    "locales": [
      "en",
      "fr"
    ],
    "localeConfigs": {
      "en": {
        "label": "English",
        "path": "en"
      },
      "fr": {
        "label": "French",
        "path": "fr"
      }
    }
  }
},
{
  "type": "localeDropdown",
  "position": "right"
}
```

--------------------------------

### Plugin Installation Shorthand and Explicit Syntax

Source: https://wordpress.github.io/wordpress-playground/blueprints/steps/shorthands

Shows how to install plugins using shorthand with an array of plugin slugs or URLs, and the equivalent explicit 'installPlugin' step for more granular control.

```json
{
	"plugins": [
		"hello-dolly",
		"https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
	]
}
```

```json
[
	{
		"step": "installPlugin",
		"pluginData": {
			"resource": "wordpress.org/plugins",
			"slug": "hello-dolly"
		}
	},
	{
		"step": "installPlugin",
		"pluginData": {
			"resource": "url",
			"url": "https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
		}
	}
]
```

--------------------------------

### Example WP-CLI Usage with Mounted Site and Blueprint

Source: https://wordpress.github.io/wordpress-playground/fr/blueprints/troubleshoot-and-debug

This example demonstrates how to set up a WordPress development environment using `npx @wp-playground/cli` with a mounted directory and a blueprint JSON file, followed by running a `wp post list` command.

```bash
mkdir wordpress
# Ensure your blueprint with the above steps is saved as, for example, './blueprint.json'
npx @wp-playground/cli server --mount-before-install=wordpress:/wordpress --blueprint=./blueprint.json
cd wordpress
wp post list
```

--------------------------------

### VS Code Debug Configuration for Xdebug

Source: https://wordpress.github.io/wordpress-playground/bn/developers/xdebug/getting-started

This is an example of a `launch.json` configuration file for VS Code, automatically generated by the `@wp-playground/cli` command. It sets up the debugger to listen for Xdebug connections on port 9003 and defines path mappings for debugging.

```json
{
    "configurations": [
        {
            "name": "WP Playground CLI - Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/": "${workspaceFolder}/.playground-xdebug-root",
                "/wordpress/wp-content/plugins/test-xdebug": "${workspaceFolder}/"
            }
        }
    ]
}

```

--------------------------------

### Blueprint Step to Run PHP Code

Source: https://wordpress.github.io/wordpress-playground/fr/blueprints/tutorial/build-your-first-blueprint

This JSON snippet demonstrates how to include a `runPHP` step within a WordPress Playground Blueprint. It executes the provided PHP code during the blueprint's setup process. The example shows the deletion of default content.

```json
{
	// ...
	"steps": [
		// ...
		{
			"step": "runPHP",
			"code": "<?php\nrequire '/wordpress/wp-load.php';\n\n$posts = get_posts(array(\n    'numberposts' => -1,\n    'post_type' => array('post', 'page'),\n    'post_status' => 'any'\n));\n\nforeach ($posts as $post) {\n    wp_delete_post($post->ID, true);\n}"
		}
	]
}

```

--------------------------------

### Run WordPress Installation Wizard (PHP)

Source: https://wordpress.github.io/wordpress-playground/gu/api/blueprints/function/runWpInstallationWizard

This function automates the WordPress installation process. It requires a UniversalPHP instance and accepts installation arguments, with an optional progress callback for monitoring the installation steps. The return type is generic.

```PHP
/**
 * Installs WordPress.
 *
 * @param UniversalPHP $php A PHP instance or Playground client.
 * @param Omit<RunWpInstallationWizardStep, 'step'> $args
 * @param StepProgress|null $progressArgs Optional progress callback.
 * @return any
 */
function runWpInstallationWizard(UniversalPHP $php, Omit $args, ?StepProgress $progressArgs = null): any;
```

--------------------------------

### Start WordPress Playground Server with Xdebug and VS Code IDE Integration

Source: https://wordpress.github.io/wordpress-playground/gu/developers/xdebug/getting-started

This command initiates a WordPress Playground server with Xdebug enabled and specifically configures it for seamless integration with VS Code. It includes the `--auto-mount` flag for automatic mounting of local directories and the experimental flag for VS Code IDE setup. This is useful for debugging WordPress plugins and themes directly from your IDE.

```bash
npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mount
```

--------------------------------

### Example Usage of Set Site Options Step

Source: https://wordpress.github.io/wordpress-playground/gu/api/blueprints

An example demonstrating how to use the `setSiteOptions` step to update the blog name and description.

```json
{
    "step": "setSiteOptions",
    "options": {
        "blogname": "My Blog",
        "blogdescription": "A great blog"
    }
}
```

--------------------------------

### importThemeStarterContent

Source: https://wordpress.github.io/wordpress-playground/es/blueprints/steps

Imports a theme Starter Content into WordPress.

```APIDOC
## importThemeStarterContent

### Description
Imports a theme Starter Content into WordPress.

### Method
POST

### Endpoint
/importThemeStarterContent

### Parameters
#### Request Body
- **themeSlug** (string) - Required - The name of the theme to import content from.

### Request Example
```json
{
    "steps": [
        {
            "step": "importThemeStarterContent"
        }
    ]
}
```

### Response
#### Success Response (200)
- **message** (string) - Success message

#### Response Example
```json
{
    "message": "Theme starter content imported successfully."
}
```
```

--------------------------------

### JavaScript API - Start Playground

Source: https://wordpress.github.io/wordpress-playground/es/blueprints/using-blueprints

Demonstrates how to initialize and start a WordPress Playground instance using the `startPlaygroundWeb` function. This includes configuring the iframe, remote URL, and setting up a WordPress environment with a blueprint.

```APIDOC
## JavaScript API - Start Playground

### Description
Initializes and starts a WordPress Playground instance within an iframe using the `@wp-playground/client` package. This function allows for configuration of the playground, including remote URL and a blueprint for setup.

### Method
`startPlaygroundWeb(options)`

### Parameters
#### Options Object
- **iframe** (HTMLElement) - Required - The iframe element where the playground will be mounted.
- **remoteUrl** (string) - Required - The URL of the remote HTML file for the playground.
- **blueprint** (object) - Optional - A configuration object for setting up the WordPress environment.
  - **landingPage** (string) - Optional - The default landing page for the playground.
  - **preferredVersions** (object) - Optional - Specifies preferred versions for PHP and WordPress.
    - **php** (string) - Optional - The preferred PHP version.
    - **wp** (string) - Optional - The preferred WordPress version.
  - **steps** (array) - Optional - An array of steps to perform during the playground setup.
    - **step** (string) - Required - The type of step (e.g., 'login', 'installPlugin').
    - **username** (string) - Required for 'login' step - The username for login.
    - **password** (string) - Required for 'login' step - The password for login.
    - **pluginData** (object) - Required for 'installPlugin' step - Data for the plugin to install.
      - **resource** (string) - Required - The resource type (e.g., 'wordpress.org/plugins').
      - **slug** (string) - Required - The slug of the plugin.

### Request Example
```javascript
import { startPlaygroundWeb } from 'https://playground.wordpress.net/client/index.js';

const client = await startPlaygroundWeb({
	iframe: document.getElementById('wp-playground'),
	remoteUrl: `https://playground.wordpress.net/remote.html`,
	blueprint: {
		landingPage: '/wp-admin/',
		preferredVersions: {
			php: '8.3',
			wp: 'latest',
		},
		steps: [
			{
				step: 'login',
				username: 'admin',
				password: 'password',
			},
			{
				step: 'installPlugin',
				pluginData: {
					resource: 'wordpress.org/plugins',
				slug: 'friends',
				},
			},
		],
	},
});
```

### Response
#### Success Response (Client Object)
- **client** (object) - An object representing the connected playground client, used for further interactions.

#### Response Example
(The `startPlaygroundWeb` function returns a client object, not a direct response body.)
```

--------------------------------

### Installing a Theme using a Blueprint (GitHub Repository)

Source: https://wordpress.github.io/wordpress-playground/fr/guides/for-theme-developers

Load and activate a theme directly from a GitHub repository using a Blueprint configuration with the `git:directory` resource.

```APIDOC
## Run Blueprint with GitHub Theme

### Description
Configures a WordPress Playground instance to install and activate a theme from a GitHub repository using a Blueprint and the `git:directory` resource.

### Method
POST (Implicitly, via Blueprint execution)

### Endpoint
`https://playground.wordpress.net/` (when using Blueprints)

### Request Body
```json
{
  "steps": [
    {
      "step": "installTheme",
      "themeData": {
        "resource": "git:directory",
        "url": "https://github.com/Automattic/themes",
        "ref": "trunk",
        "path": "assembler"
      },
      "options": {
        "activate": true
      }
    }
  ]
}
```

### Parameters
#### Request Body Fields
- **steps** (array) - Required - An array of steps to execute in the Playground.
  - **step** (string) - Required - Must be `installTheme`.
  - **themeData** (object) - Required - Data for the theme to install.
    - **resource** (string) - Required - Set to `git:directory`.
    - **url** (string) - Required - The URL of the GitHub repository.
    - **ref** (string) - Required - The branch, tag, or commit hash to use (e.g., `trunk`).
    - **path** (string) - Optional - The path to the theme directory within the repository.
  - **options** (object) - Optional - Options for theme installation.
    - **activate** (boolean) - Optional - Whether to activate the theme after installation.

### Request Example
(See Request Body above)

### Response
#### Success Response (200)
Launches a live WordPress environment with the specified theme from the GitHub repository installed and activated.

#### Response Example
(Browser window opens with WordPress Playground running the specified theme)
```

--------------------------------

### IDE Integration for Xdebug Debugging with VS Code

Source: https://wordpress.github.io/wordpress-playground/bn/developers/xdebug/getting-started

This command enables Xdebug and integrates with VS Code for debugging. It automatically configures Xdebug path mappings and web server details in the IDE's launch configuration. Ensure you have the PHP Debug extension installed and breakpoints enabled in your IDE.

```bash
npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mount  

```

--------------------------------

### StartPlaygroundOptions

Source: https://wordpress.github.io/wordpress-playground/api/client/interface/StartPlaygroundOptions

Configuration options for initializing the WordPress Playground.

```APIDOC
## StartPlaygroundOptions

### Description
Configuration options for initializing the WordPress Playground.

### Method
N/A (Configuration Object)

### Endpoint
N/A (Initialization)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
##### __blueprint (BlueprintV1) - Optional
Blueprint definition for setting up the WordPress environment.

##### __corsProxy (string) - Optional
Proxy URL to use for cross-origin requests. If set, requests to external URLs will be made through this proxy.

##### __disableProgressBar (boolean) - Optional
Disables the progress bar during playground initialization.

##### __experimentalBlueprintsV2Runner (boolean) - Optional
Enables the experimental Blueprints v2 PHP runner instead of TypeScript steps.

##### __gitAdditionalHeadersCallback (function) - Optional
A callback function that returns additional headers to pass to git operations based on the URL being accessed.
  * Type: `(url: string) => Record<string, string>`

##### __iframe (HTMLIFrameElement) - Required
The iframe element where the playground will be rendered.

##### __mounts (MountDescriptor[]) - Optional
An array of descriptors for mounting filesystems or directories into the playground.

##### __onBlueprintStepCompleted (function) - Optional
A callback function executed after each blueprint step is completed.

##### __onBlueprintValidated (function) - Optional
A callback function executed after the blueprint has been validated.
  * Type: `(blueprint: BlueprintV1Declaration) => void`

##### __onClientConnected (function) - Optional
A callback function executed when the playground client is connected, before blueprint steps are run.
  * Type: `(playground: PlaygroundClient) => void`

##### __pathAliases (PathAlias[]) - Optional
Defines path aliases to map URL prefixes to filesystem paths within the playground.
* Example:
```javascript
pathAliases: [
  { urlPrefix: '/phpmyadmin', fsPath: '/tools/phpmyadmin' }
]
```

##### __progressTracker (ProgressTracker) - Optional
An object to track the progress of playground operations.

##### __remoteUrl (string) - Required
The URL of the remote resource to load into the playground.

##### __scope (string) - Optional
A string prefix used in the site URL served by the currently running remote.html.

##### __shouldInstallWordPress (boolean) - Optional
Determines whether WordPress should be installed if not already present.

##### __sqliteDriverVersion (string) - Optional
The version of the SQLite driver to use. Defaults to the latest development version.

##### __wordpressInstallMode (WordPressInstallMode) - Optional
Specifies how to handle WordPress installation. Defaults to 'install-from-existing-files-if-needed'.

### Request Example
```json
{
  "__iframe": "<iframe id=\"playground\"></iframe>",
  "__remoteUrl": "https://github.com/WordPress/wordpress-playground.git",
  "__scope": "playground",
  "__shouldInstallWordPress": true
}
```

### Response
#### Success Response (200)
N/A (This is an initialization configuration, not an endpoint returning data)

#### Response Example
N/A
```

--------------------------------

### Install WordPress using runWpInstallationWizard

Source: https://wordpress.github.io/wordpress-playground/ja/api/blueprints/function/runWpInstallationWizard

The runWpInstallationWizard function installs WordPress. It requires a PHP instance or Playground client and installation arguments. An optional progress argument can be provided to track the installation steps. The function returns any output generated during the installation process.

```typescript
declare function runWpInstallationWizard(php: UniversalPHP, args: Omit<RunWpInstallationWizardStep, "step">, progressArgs?: StepProgress): any;
```

--------------------------------

### Install Plugin from ZIP URL using Blueprint

Source: https://wordpress.github.io/wordpress-playground/blueprints/tutorial/build-your-first-blueprint

This Blueprint demonstrates installing a WordPress plugin directly from a ZIP file hosted at a URL. It's an efficient way to deploy plugins without manual file creation within the Blueprint.

```json
{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"login": true,
	"siteOptions": {
		"blogname": "My first Blueprint"
	},
	"steps": [
		{
			"step": "installTheme",
			"themeData": {
				"resource": "wordpress.org/themes",
				"slug": "adventurer"
			}
		},
		{
			"step": "installPlugin",
			"pluginData": {
				"resource": "url",
				"url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
			}
		}
	]
}
```

--------------------------------

### Install Pendant Theme via URL

Source: https://wordpress.github.io/wordpress-playground/bn/developers/apis/query-api

This example demonstrates how to install the 'pendant' theme in WordPress Playground by appending the 'theme' parameter to the Playground URL. The Playground automatically installs the theme and logs the user in as an admin.

```html
<iframe src="https://playground.wordpress.net/?theme=pendant"></iframe>
```

--------------------------------

### Manually Install wp-playground Skill

Source: https://wordpress.github.io/wordpress-playground/guides/agent-skill-wp-playground

Manually installs the wp-playground agent skill by cloning the agent-skills repository, building the skillpack, and then installing it into your WordPress project. This method provides more control and is useful for development or custom setups.

```bash
# Clone agent-skills
git clone https://github.com/WordPress/agent-skills.git
cd agent-skills

# Build the distribution
node shared/scripts/skillpack-build.mjs --clean

# Install into your WordPress project
node shared/scripts/skillpack-install.mjs --dest=../your-wp-project --targets=codex,vscode,claude,cursor,antigravity,gemini
```

--------------------------------

### Mount Local Plugin Directory using runCLI

Source: https://wordpress.github.io/wordpress-playground/bn/developers/local-development/wp-playground-cli

Demonstrates how to mount a local directory as a plugin into the WordPress environment using the `runCLI` function with the `mount-before-install` option. The `hostPath` should be relative to the script's execution location.

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

```

--------------------------------

### Install Theme and Plugin using WordPress Playground Blueprints

Source: https://wordpress.github.io/wordpress-playground/blueprints/examples

This Blueprint installs a specified plugin and theme from WordPress.org. It requires the plugin and theme slugs to be provided.

```json
{
	"steps": [
		{
			"step": "installPlugin",
			"pluginData": {
				"resource": "wordpress.org/plugins",
				"slug": "coblocks"
			}
		},
		{
			"step": "installTheme",
			"themeData": {
				"resource": "wordpress.org/themes",
				"slug": "pendant"
			}
		}
	]
}
```

--------------------------------

### importThemeStarterContent

Source: https://wordpress.github.io/wordpress-playground/blueprints/steps

Imports a theme Starter Content into WordPress.

```APIDOC
## importThemeStarterContent

### Description
Imports a theme Starter Content into WordPress.

### Method
POST

### Endpoint
/importThemeStarterContent

### Parameters
#### Request Body
- **themeSlug** (string) - Required - The name of the theme to import content from.

### Request Example
```json
{
    "steps": [
        {
            "step": "importThemeStarterContent"
        }
    ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
    "status": "Theme starter content imported successfully"
}
```
```

--------------------------------

### Install Pendant Theme via URL

Source: https://wordpress.github.io/wordpress-playground/developers/apis/query-api

This example demonstrates how to install the 'pendant' theme in WordPress Playground by appending the 'theme' query parameter to the Playground URL. This action automatically installs the theme and logs the user in as an admin.

```url
https://playground.wordpress.net/?theme=pendant
```

--------------------------------

### Mount Before Installation with Playground CLI

Source: https://wordpress.github.io/wordpress-playground/developers/local-development/wp-playground-cli

Starts the Playground CLI server and mounts local project files before WordPress installation begins. This can help override the boot process and connect with WP-CLI.

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

--------------------------------

### Start Playground CLI Server with Auto-Mount for Plugin Debugging

Source: https://wordpress.github.io/wordpress-playground/bn/developers/xdebug/getting-started

This command starts the Playground CLI server with Xdebug, the experimental DevTools debugger, and the auto-mount flag. The auto-mount feature automatically detects and mounts plugin folders, enabling direct debugging of your plugin code within DevTools.

```bash
npx @wp-playground/cli@latest server --xdebug --experimental-devtools --auto-mount
```
Tokens:
Raw