WordPress Playground

https://github.com/wordpress/wordpress-playground
Admin
WordPress Playground is an experimental in-browser WordPress that runs without a PHP server using...
Tokens:387,802
Snippets:2,705
Trust Score:9
License:GPL-2.0
Update:5 days ago
Show doc for...
Tokens:
Raw
### Blueprint example: install plugin, login, and open editor

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/playground/cli/README.md

A Blueprint JSON file that installs the Gutenberg plugin, logs in as admin, and opens the new post editor. This example demonstrates the structure of a Blueprint with steps.

```json
{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"landingPage": "/wp-admin/post-new.php",
	"steps": [
		{
			"step": "installPlugin",
			"pluginZipFile": {
				"resource": "wordpress.org/plugins",
				"slug": "gutenberg"
			},
			"options": {
				"activate": true
			}
		},
		{
			"step": "login",
			"username": "admin",
			"password": "password"
		}
	]
}
```

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

### Install plugins with the `plugins` shorthand

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/guides/for-plugin-developers.md

Use the `plugins` shorthand in a Blueprint to install your plugin along with any dependencies. The example sets the landing page to the plugins admin page and enables login.

```json
{
	"landingPage": "/wp-admin/plugins.php",
	"plugins": ["gutenberg", "sql-buddy", "create-block-theme"],
	"login": true
}
```

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

### Starting a Playground server with runCLI

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/guides/e2e-testing-with-playwright.md

Starts a local Playground server using runCLI with a Blueprint that installs WooCommerce. Returns an object with serverUrl and server.

```typescript
const cli = await runCLI({
	command: 'server',
	blueprint: {
		preferredVersions: { php: '8.3', wp: 'latest' },
		login: true,
		steps: [
			{
				step: 'installPlugin',
				pluginData: {
					resource: 'wordpress.org/plugins',
					slug: 'woocommerce',
				},
			},
		],
	},
});
```

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

### Quickstart: server command with --auto-mount

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/playground/cli/README.md

Runs WordPress locally with explicit low-level control over mounts, storage, or CI setup.

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

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

### Clone Gutenberg and start dev server

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/contributing/contributor-day.md

Clone the Gutenberg repository, install dependencies, and run the development server. This is the initial setup for creating a Pull Request.

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

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

### Quickstart: start command

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/playground/cli/README.md

Runs WordPress locally with automatic project type detection, persistence, and browser opening. Requires Node.js 20.18 or higher.

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

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

### Setup commands for running from source

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/playground/cli/README.md

Commands to clone the repository and install dependencies. Includes steps for cloning with submodules and alternative submodule update if already cloned.

```bash
# If you don't have the repository cloned yet:
git clone -b trunk --single-branch --depth 1 --recurse-submodules https://github.com/WordPress/wordpress-playground.git
cd wordpress-playground

# Alternatively, if you already have a clone but forgot to
# pull the submodules, you can run:
cd wordpress-playground
git submodule update --init --recursive

nvm use 23
npm install
```

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

### installTheme Function API example

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/static/handbook/blueprints-steps.md

TypeScript example calling the installTheme function from @wp-playground/blueprints. It installs the Pendant theme from wordpress.org, activates it, and imports starter content.

```ts
import { installTheme } from '@wp-playground/blueprints';

installTheme(
	playground,
	{
		themeData: {
			resource: 'wordpress.org/themes',
			slug: 'pendant',
		},
		options: {
			activate: true,
			importStarterContent: true,
		},
	},
	progress
);
```

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

### Run start command inside a plugin or theme directory

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md

When run inside a plugin or theme directory, the `start` command automatically mounts the project. This example shows changing to the project directory and then running the command.

```bash
cd my-plugin
npx @wp-playground/cli@latest start
```

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

### Start WordPress Playground server with Xdebug using npx

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/07-xdebug/02-getting-started.md

Use this command to quickly start a WordPress server with Xdebug enabled. It runs on http://127.0.0.1:9400 and requires no installation. Only one project can be debugged at a time.

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

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

### Blueprint JSON example (my-blueprint.json)

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md

Example Blueprint file that sets the landing page to the Akismet settings, enables login, and installs two plugins: 'hello-dolly' and a custom plugin from a URL.

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

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

### installPlugin Function API example

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/static/handbook/blueprints-steps.md

TypeScript example calling the installPlugin function from @wp-playground/blueprints. It installs the Gutenberg plugin from wordpress.org and activates it, passing a playground instance and progress object.

```ts
import { installPlugin } from '@wp-playground/blueprints';

installPlugin(
	playground,
	{
		pluginData: {
			resource: 'wordpress.org/plugins',
			slug: 'gutenberg',
		},
		options: {
			activate: true,
		},
	},
	progress
);
```

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

### Initial Setup: nvm use and npm ci

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/AGENTS.md

Run these commands from a fresh clone or new worktree to set up the repository before building, testing, or running dev servers. This is especially important for worktree-based agent tools that may not install dependencies automatically.

```bash
nvm use
npm ci
```

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

### installPlugin Blueprint API example (git:directory)

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/static/handbook/blueprints-steps.md

Blueprint JSON to install a plugin from a Git repository directory. Uses the 'installPlugin' step with 'pluginData' resource 'git:directory', pointing to the WordPress Playground repository, and activates the plugin.

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

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

### Blueprint API example: importThemeStarterContent step

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/static/handbook/blueprints-steps.md

Minimal Blueprint JSON that imports starter content from the active theme. The theme must already be installed; if it has no starter content, this step does nothing.

```json
{
	"step": "importThemeStarterContent"
}
```

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

### Load an extension with extra files and environment variables

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/06-apis/javascript-api/07-php-extensions.md

This example stages a data file in the virtual filesystem and sets an environment variable pointing to its directory before PHP starts.

```ts
await loadNodeRuntime('8.4', {
	extensions: [
		{
			name: 'my_text_extension',
			source: { format: 'so', bytes },
			env: {
				MY_TEXT_DATA: '/internal/shared/my_text_extension',
			},
			extraFiles: {
				files: {
					'/internal/shared/my_text_extension/data.bin': dataBytes,
				},
			},
		},
	],
});
```

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

### Provide a full Blueprint with the direct action

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/guides/github-action-pr-preview.md

Use the `blueprint` input to provide a full Blueprint JSON string directly in the workflow. This example installs a plugin from the PR repository, installs and activates WooCommerce, and logs in as admin.

```yaml
- uses: WordPress/action-wp-playground-pr-preview@v3
  with:
      blueprint: |
          {
            "$schema": "https://playground.wordpress.net/blueprint-schema.json",
            "preferredVersions": { "php": "8.3", "wp": "6.6" },
            "steps": [
              {
                "step": "installPlugin",
                "pluginData": {
                  "resource": "git:directory",
                  "url": "https://github.com/${{ github.repository }}.git",
                  "ref": "${{ github.event.pull_request.head.ref }}",
                  "path": "/"
                },
                "options": { "activate": true }
              },
              {
                "step": "installPlugin",
                "pluginData": {
                  "resource": "wordpress.org/plugins",
                  "slug": "woocommerce"
                },
                "options": { "activate": true }
              },
              { "step": "login", "username": "admin" }
            ]
          }
      github-token: ${{ secrets.GITHUB_TOKEN }}

```

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

### Quick start: list, keep, and get client

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/06-apis/sites-api/01-index.md

Run in DevTools after WordPress loads on playground.wordpress.net. Wait for the API to be ready, then list sites, keep the active autosave as a permanent browser Playground, and use the client to list files.

```javascript
await playgroundSites.isReady();

playgroundSites.list();
// → [{ slug: 'calm-sunny-park', name: 'Calm Sunny Park', storage: 'opfs', persistence: 'autosave', isActive: true }]

await playgroundSites.keep(undefined, 'My demo site');
// The active autosave is now a permanently saved browser Playground.

const client = playgroundSites.getClient();
await client.listFiles('/wordpress');
```

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

### installTheme Blueprint API example

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/static/handbook/blueprints-steps.md

Blueprint JSON to install the Pendant theme from wordpress.org, activate it, and import starter content. Uses the 'installTheme' step with 'themeData' resource 'wordpress.org/themes' and slug 'pendant'.

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

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

### Install @php-wasm/node-8-4 directly

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/05-local-development/03-php-wasm-node.md

Installs @php-wasm/universal and @php-wasm/node-8-4 to load a specific PHP version without @php-wasm/node, bypassing Node.js-specific setup.

```bash
npm install @php-wasm/universal @php-wasm/node-8-4
```

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

### Programmatic usage with runCLI

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/playground/cli/README.md

Use the runCLI function from @wp-playground/cli to start a Playground server programmatically. The example starts a server with PHP 8.3, latest WordPress, and enables login.

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

let cliServer: RunCLIServer;

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

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

### Complete Blueprint: Write plugin, activate, and import starter content

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/static/handbook/blueprints-steps.md

This Blueprint writes a PHP plugin that registers starter content (a Home page) for the active theme, activates it, and then imports the starter content. The plugin runs on 'after_setup_theme' at priority 100, replacing previously registered starter content. All plugin code is inline; no external PHP file is needed.

```json
{
	"steps": [
		{
			"step": "writeFile",
			"path": "/wordpress/wp-content/plugins/theme-starter-content.php",
			"data": "<?php\n// Plugin Name: Theme Starter Content\nadd_action( 'after_setup_theme', function () {\n    add_theme_support( 'starter-content', array(\n        'posts' => array(\n            'home' => array(\n                'post_type' => 'page',\n                'post_title' => 'Home',\n                'post_content' => 'Welcome to my Playground!'\n            )\n        ),\n        'options' => array(\n            'show_on_front' => 'page',\n            'page_on_front' => '{{home}}'\n        )\n    ) )\n}, 100 );"
		},
		{
			"step": "activatePlugin",
			"pluginPath": "theme-starter-content.php"
		},
		{
			"step": "importThemeStarterContent"
		}
	]
}
```

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

### Start dev server with PR preview mocks

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/playground/website/README.md

Run this command to start the website with deterministic verification responses for testing the pull-request preview interface locally. Only verification requests for the reserved PR numbers are mocked; other PR numbers and artifact downloads continue through the normal plugin proxy.

```bash
PLAYGROUND_PR_PREVIEW_MOCKS=true npm run dev
```

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

### Embed Playground with Query API to install plugin

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/03-build-an-app/01-index.md

Use an iframe with the Query API parameter 'plugin' to preinstall a plugin from the WordPress directory. The example installs the 'coblocks' plugin.

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

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

### Quick start: startPlaygroundWeb with iframe

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/06-apis/javascript-api/01-index.md

Minimal HTML page that loads the Playground client from unpkg, starts it in an iframe using the special /remote.html URL, and waits until it is ready.

```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>
```

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

### Configure steps: login and install Gutenberg plugin

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/blueprints/03-data-format.md

Uses the steps property to log in with a dedicated username and password, then installs and activates the Gutenberg plugin. Steps allow preinstalling themes, plugins, and demo content.

```js
{
	"steps": [
		{
			"step": "login",
			"username": "admin",
			"password": "password"
		},
		{
			"step": "installPlugin",
			"pluginData": {
				"resource": "wordpress.org/plugins",
				"slug": "gutenberg"
			}
		},
	]
}
```

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

### cp Blueprint API example

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/static/handbook/blueprints-steps.md

Copies a file from one path to another within the WordPress installation.

```json
{
	"step": "cp",
	"fromPath": "/wordpress/index.php",
	"toPath": "/wordpress/index2.php"
}
```

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

### start

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/playground/cli/README.md

Starts a local WordPress server with automatic project detection, site persistence, and browser opening. Supports various optional arguments to customize the WordPress version, PHP version, port, and more.

```APIDOC
## start

### Description
Starts a local WordPress server with automatic project detection, site persistence, and browser opening.

### Method
CLI Command

### Command
`npx @wp-playground/cli@latest start [options]`

### Parameters
#### Optional Arguments
- `--path=<path>` (string) - Optional - Path to the project directory. Defaults to the current working directory.
- `--wp=<version>` (string) - Optional - WordPress version to use. Defaults to the latest.
- `--php=<version>` (string) - Optional - PHP version to use. Defaults to PHP 8.3.
- `--port=<port>` (number) - Optional - The port number for the server to listen on. Defaults to 9400 when available.
- `--blueprint=<path>` (string) - Optional - The path to a JSON Blueprint file to execute.
- `--login` (boolean) - Optional - Automatically log the user in as an administrator. Defaults to true.
- `--skip-browser` (boolean) - Optional - Do not open the site in your default browser.
- `--reset` (boolean) - Optional - Delete the stored site directory and start fresh.
- `--no-auto-mount` (boolean) - Optional - Disable automatic project detection.

### Example
```bash
npx @wp-playground/cli@latest start --path=/my/project --wp=6.5 --php=8.2 --port=8080
```

### Response
Starts a local WordPress server and opens the site in the default browser (unless `--skip-browser` is used).
```

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

### Blueprint to install plugin from GitHub file

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/guides/for-plugin-developers.md

Use this Blueprint to launch WP Playground with a plugin fetched from a raw GitHub URL. It logs in, writes the plugin file to /wordpress/wp-content/plugins/cpt-books.php, and activates it via activatePlugin with pluginPath cpt-books.php.

```json
{
	"landingPage": "/wp-admin/plugins.php",
	"login": true,
	"steps": [
		{
			"step": "login"
		},
		{
			"step": "writeFile",
			"path": "/wordpress/wp-content/plugins/cpt-books.php",
			"data": {
				"resource": "url",
				"url": "https://raw.githubusercontent.com/WordPress/blueprints/trunk/blueprints/custom-post/books.php"
			}
		},
		{
			"step": "activatePlugin",
			"pluginPath": "cpt-books.php"
		}
	]
}
```

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

### activateTheme Blueprint API example

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/static/handbook/blueprints-steps.md

Activates a WordPress theme by its folder name. The theme must be installed in wp-content/themes/.

```json
{
	"step": "activateTheme",
	"themeFolderName": "storefront"
}
```

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

### Create directory and write file with mkdir and writeFile steps

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/blueprints/09-troubleshoot-and-debug-blueprints.md

Use these steps together to create a missing parent directory and then write a file into it. The mkdir step creates the directory, and the writeFile step writes the plugin file content.

```json
[
	{
		"step": "mkdir",
		"path": "/wordpress/wp-content/plugins/example"
	},
	{
		"step": "writeFile",
		"path": "/wordpress/wp-content/plugins/example/index.php",
		"data": "<?php /* Plugin Name: Example */"
	}
]
```

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

### Simple Blueprint JSON example

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/blueprints/tutorial/01-what-are-blueprints-what-you-can-do-with-them.md

A basic Blueprint that installs the Akismet and Gutenberg plugins, installs the Twenty Nineteen theme, sets the site name and description, and enables WordPress debugging mode via the WP_DEBUG constant.

```json
{
	"plugins": ["akismet", "gutenberg"],
	"steps": [
		{
			"step": "installTheme",
			"themeData": {
				"resource": "wordpress.org/themes",
				"slug": "twentynineteen"
			}
		}
	],
	"siteOptions": {
		"blogname": "My Blog",
		"blogdescription": "Just another WordPress site"
	},
	"constants": {
		"WP_DEBUG": true
	}
}
```

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

### CLI usage examples for xdebug-bridge

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/php-wasm/xdebug-bridge/README.md

Shows how to start the bridge with default settings, custom port and verbose logging, and display help.

```bash
# Start with default settings
npx xdebug-bridge

# Custom port and verbose logging
npx xdebug-bridge --port 9000 --verbosity debug

# Show help
npx xdebug-bridge --help
```

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

### Run Playground CLI with start command

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md

Use `npx @wp-playground/cli@latest start` to start a local WordPress environment with auto-detection of project type, persistence, and automatic browser opening.

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

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

### Blueprint using importThemeStarterContent step

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/guides/providing-content-for-your-demo.md

This blueprint installs two themes (twentytwenty and twentytwentyone) and then uses the importThemeStarterContent step to publish the starter content of the twentytwenty theme, even though it is not activated.

```json
{
	"$schema": "https://playground.wordpress.net/blueprint-schema.json",
	"steps": [
		{
			"step": "installTheme",
			"themeData": {
				"resource": "wordpress.org/themes",
				"slug": "twentytwenty"
			}
		},
		{
			"step": "installTheme",
			"themeData": {
				"resource": "wordpress.org/themes",
				"slug": "twentytwentyone"
			},
			"options": {
				"activate": true
			}
		},
		{
			"step": "importThemeStarterContent",
			"themeSlug": "twentytwenty"
		}
	]
}
```

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

### Define a typed blueprint with BlueprintDeclaration

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/guides/programmatic-playground-cli.md

Imports the `BlueprintDeclaration` type from `@wp-playground/blueprints` to define a blueprint with full type-safety. The example installs and activates a theme.

```TypeScript
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
      }
    }
  ]
};
```

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

### Local preview commands

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/contributing/documentation.md

Run these commands in the cloned repository to build and serve the documentation site locally. The site opens in a new browser tab and refreshes automatically with each change.

```bash
npm install
npm run build:docs
npm run dev:docs
```

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

### runPHP Blueprint API example

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/static/handbook/blueprints-steps.md

Blueprint step to run PHP code. When using WordPress functions, the code must load wp-load.php and start with the required prefix.

```json
{
	"step": "runPHP",
	"code": "<?php require_once '/wordpress/wp-load.php'; wp_insert_post(array('post_title' => 'wp-load.php required for WP functionality', 'post_status' => 'publish')); ?>"
}
```

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

### Run end-to-end tests

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/playground/website/README.md

Run this command to execute the end-to-end tests for the playground-website package. See the Playwright guide for browser installation, UI mode, and CI commands.

```bash
npx nx e2e playground-website
```

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

### Create a plugin file with the `writeFile` step

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/guides/for-plugin-developers.md

Use the `writeFile` step to create any plugin file on the fly, referencing code from a *.php file stored on GitHub or Gist. The example places a plugin that generates Custom Post Types in the `mu-plugins` folder to ensure it runs automatically on load.

```json
{
	"landingPage": "/wp-admin/",
	"login": true,
	"steps": [
		{
			"step": "writeFile",
			"path": "/wordpress/wp-content/mu-plugins/books.php",
			"data": {
				"resource": "url",
				"url": "https://raw.githubusercontent.com/wordpress/blueprints/trunk/blueprints/custom-post/books.php"
			}
		}
	]
}
```

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

### server

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/playground/cli/README.md

Starts a local WordPress server with full manual control over configuration. Supports many options for mounting directories, setting WordPress and PHP versions, and controlling the installation process.

```APIDOC
## server

### Description
Starts a local WordPress server with full manual control over configuration.

### Method
CLI Command

### Command
`npx @wp-playground/cli@latest server [options]`

### Parameters
#### Optional Arguments
- `--port=<port>` (number) - Optional - The port number for the server to listen on. Defaults to 9400.
- `--wp=<version>` (string) - Optional - The version of WordPress to use. Defaults to the latest.
- `--php=<version>` (string) - Optional - PHP version to use. Defaults to PHP 8.3.
- `--auto-mount` (boolean) - Optional - Automatically mount the current directory (plugin, theme, wp-content, etc.).
- `--mount=<mapping>` (string) - Optional - Manually mount a directory (can be used multiple times). Format: `/host/path:/vfs/path`.
- `--mount-before-install` (string) - Optional - Mount a directory to the PHP runtime before WordPress installation (can be used multiple times). Format: `/host/path:/vfs/path`.
- `--mount-dir` (string) - Optional - Mount a directory to the PHP runtime (can be used multiple times). Format: `"/host/path" "/vfs/path"`.
- `--mount-dir-before-install` (string) - Optional - Mount a directory before WordPress installation (can be used multiple times). Format: `"/host/path" "/vfs/path"`.
- `--blueprint=<path>` (string) - Optional - The path to a JSON Blueprint file to execute.
- `--blueprint-may-read-adjacent-files` (boolean) - Optional - Consent flag: Allow "bundled" resources in a local blueprint to read files in the same directory as the blueprint file.
- `--login` (boolean) - Optional - Automatically log the user in as an administrator.
- `--mode=<mode>` (string) - Optional - Choose how Blueprint v2 prepares the site: `create-new-site`, `apply-to-existing-site`, or `mount-only`. Cannot be combined with `--auto-mount`, `--wordpress-install-mode`, or `--skip-sqlite-setup`.
- `--wordpress-install-mode <mode>` (string) - Optional - Control how Playground prepares WordPress before booting. Defaults to `download-and-install`. Other options: `install-from-existing-files`, `install-from-existing-files-if-needed`, and `do-not-attempt-installing`.
- `--skip-sqlite-setup` (boolean) - Optional - Do not set up the SQLite database integration.
- `--verbosity` (string) - Optional - Output logs and progress messages (choices: "quiet", "normal", "debug"). Defaults to "normal".
- `--debug` (boolean) - Optional - Print the PHP error log if an error occurs during boot.
- `--follow-symlinks` (boolean) - Optional - Allow Playground to follow symlinks by automatically mounting symlinked directories and files encountered in mounted directories. ⚠️ Warning: Following symlinks will expose files outside mounted directories to Playground and could be a security risk.
- `--workers=<n|auto>` (string) - Optional - Number of request-handling worker threads. Pass a positive integer, or `auto` to use one worker per CPU core (minus one). Defaults to `min(6, cpus-1)`. Useful for multi-client workloads (e.g. parallel e2e suites) that need more than 6 in-flight requests.
- `--experimental-multi-worker` (boolean) - Optional - Deprecated. Use `--workers=<n|auto>` instead. The value of this flag is ignored.
- `--phpmyadmin[=<path>]` (string) - Optional - Install phpMyAdmin for database management. The phpMyAdmin URL will be printed after boot. Optionally specify a custom URL path (default: `/phpmyadmin`).
- `--internal-cookie-store` (boolean) - Optional - Enables Playground's internal cookie handling. When active, Playground uses an HttpCookieStore to manage and persist cookies across requests. If disabled, cookies are handled externally, like by a browser in Node.js.
- `--php-extension=<manifest>` (string) - Optional - Load a custom PHP.wasm extension manifest before PHP starts. Accepts local paths, `file:` URLs, and `http(s):` URLs. Can be used multiple times.

### Example
```bash
npx @wp-playground/cli@latest server --port=8080 --wp=6.5 --php=8.2 --mount=/host/path:/vfs/path
```

### Response
Starts a local WordPress server with the specified configuration.
```

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

### GitDirectoryReference example

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/blueprints/04-resources.md

JSON example of using GitDirectoryReference in an installPlugin step. Shows how to reference a plugin in a subdirectory of a repository.

```json
{
	"step": "installPlugin",
	"pluginData": {
		"resource": "git:directory",
		"url": "https://github.com/WordPress/block-development-examples",
		"ref": "HEAD",
		"path": "plugins/data-basics-59c8f8"
	},
	"options": {
		"activate": true,
		"targetFolderName": "data-basics"
	}
}
```

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

### Mount a local plugin directory with mount-before-install

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/guides/programmatic-playground-cli.md

Starts a Playground server with login enabled and mounts a local plugin directory before installation. The `hostPath` is relative to the script's execution directory.

```TypeScript
import { runCLI } from "@wp-playground/cli";

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

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

### Checkout and test a Gutenberg PR

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/contributing/contributor-day.md

Checkout the branch of a Gutenberg PR, pull the latest changes, install dependencies, and run the dev server. Then start WordPress with @wp-playground/cli in a separate terminal.

```bash
# copy the branch-name from GitHub #
git checkout branch-name
git pull
npm install
npm run dev

# In a different terminal inside the Gutenberg directory *
npx @wp-playground/cli@latest server --auto-mount
```

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

### Terminal output when starting Xdebug and DevTools

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/developers/07-xdebug/02-getting-started.md

Example output showing the server startup sequence, the CDP URL to connect Chrome DevTools, and the Xdebug receiver initialization on port 9003.

```bash
Starting a PHP server...
Setting up WordPress latest
Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.3.zip
Fetching SQLite integration plugin...
Booting WordPress...
WordPress is running on http://127.0.0.1:9400 with 1 worker(s)
Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9229

Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...
```

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

### Manifest with iniEntries and env

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/php-wasm/compile-extension/README.md

Shows how to add startup settings to the manifest using iniEntries and env. Empty directories are recorded as type: "directory" nodes.

```json
{
	"name": "spx",
	"version": "0.1.0",
	"artifacts": [
		{
			"phpVersion": "8.4",
			"sourcePath": "spx-php8.4-jspi.so"
		}
	],
	"iniEntries": {
		"spx.http_enabled": "1"
	},
	"env": {
		"SPX_DATA_DIR": "/internal/shared/spx/data"
	}
}
```

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

### Blueprint: setting options and creating content

Source: https://github.com/wordpress/wordpress-playground/blob/trunk/packages/docs/site/docs/main/guides/e2e-testing-with-playwright.md

Uses setSiteOptions to set the site name and permalink structure, then runs PHP to insert a test post.

```typescript
const blueprint = {
	login: true,
	steps: [
		{
			step: 'setSiteOptions',
			options: {
				blogname: 'Test Site',
				permalink_structure: '/%postname%/',
			},
		},
		{
			step: 'runPHP',
			code: `<?php
        require '/wordpress/wp-load.php';
        wp_insert_post([
          'post_title' => 'Test Post',
          'post_content' => '<!-- wp:paragraph --><p>Hello World</p><!-- /wp:paragraph -->',
          'post_status' => 'publish',
        ]);
      `,
		},
	],
};
```
Tokens:
Raw