Skip to main content

Quick Start Guide for Developers

WordPress Playground was created as a programmable tool. Below you'll find a few examples of what you can do with it. Each discussed API is described in detail in the APIs section:

Embed WordPress on your website​

Playground can be embedded on your website using the HTML <iframe> tag as follows:

<iframe src="https://playground.wordpress.net/"></iframe>

Every visitor will get their own private WordPress instance for free. You can then customize it using one of the Playground APIs.

Careful with the demo site

The site at https://playground.wordpress.net is there to support the community, but there are no guarantees it will continue to work if the traffic grows significantly.

If you need certain availability, you should host your own WordPress Playground.

Control the embedded website​

WordPress Playground provides three APIs you can use to control the iframed website. All the examples in this section are built using one of these:

  • Query API enable basic operations using only query parameters
  • Blueprints API give you a great degree of control with a simple JSON file
  • JavaScript API give you full control via a JavaScript client from an npm package

Learn more about each of these APIs in the APIs overview section.

Showcase a plugin or theme from WordPress directory​

You can install plugins and themes from the WordPress directory with only URL parameters. For example this iframe would come with the coblocks and friends plugins preinstalled as well as the pendant theme.

This is called Query API and you can learn more about it here.

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

Showcase any plugin or theme​

What if your plugin is not in the WordPress directory?

You can still showcase it on Playground by using JSON Blueprints. For example, this Blueprint would download and install a plugin and a theme from your website and also import some starter content:

{
    "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",
            "pluginData": {
                "resource": "url",
                "url": "https://your-site.com/starter-content.wxr"
            }
        }
    ]
}

See getting started with Blueprints to learn more.

Preview pull requests from your repository​

See the live example of Gutenberg PR previewer.

You can use Playground as a Pull Request previewer if:

  • Your WordPress plugin or theme uses a CI pipeline
  • Your CI pipeline bundles your plugin or theme
  • You can expose the zip file generated by your CI pipeline publicly

Those zip bundles aren't any different from regular WordPress Plugins, which means you can install them in Playground using the JSON Blueprints API. Once you exposed an endpoint like https://your-site.com/pull-request-1234.zip, the following Blueprint will do the rest:

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

The official Playground demo uses this technique to preview pull requests from the Gutenberg repository:

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

Build a compatibility testing environment​

A live plugin demo with a configurable PHP and WordPress makes an excellent compatibility testing environment.

With the Query API, you'd simply add the php and wp query parameters to the URL:

<iframe src="https://playground.wordpress.net/?php=7.4&wp=6.1"></iframe>

With JSON Blueprints, you'd use the preferredVersions property:

{
    "preferredVersions": {
        "php": "7.4",
        "wp": "6.1"
    }
}

Run PHP code in the browser​

The JavaScript API provides the run() method which you can use to run PHP code in the browser:

<iframe id="wp"></iframe>
<script type="module">
    const client = await startPlaygroundWeb({
        iframe: document.getElementById('wp'),
        remoteUrl: 'https://playground.wordpress.net/remote.html',
    });
    await client.isReady;
    await client.run({
        code: `<?php
        require("/wordpress/wp-load.php");

        update_option("blogname", "Playground is really cool!");
        echo "Site title updated!";
        `,
    });
    client.goTo('/');
</script>

Combine that with a code editor like Monako or CodeMirror, and you'll get live code snippets like in this article!