WordPress Playground is a serverless version of WordPress that runs entirely in the browser. In this article, we’ll discuss the trio of APIs that form the backbone of how you use the WordPress Playground: the Query API, the Blueprints API, and the JavaScript API.

These APIs can be used individually or in combination to create a customized WordPress development environment. The degree of control each grants over your WordPress Playground instance rises along with the complexity of the API in question.

The Query API requires no code at all, relying on parameters supplied in the Playground URL. The Blueprint API can be considered “low code,” using a JSON Blueprint to configure the Playground API client. Finally, the JavaScript API is aligned with developer needs, granting complete control and allowing you to create not just WordPress sites, but new applications.

What is WordPress Playground?

Created by Adam Zielinski, Playground runs PHP as a WebAssembly binary, replaces MySQL with SQLite, and implements a web server in JavaScript as a Service Worker.

It provides instant access to an in-browser WordPress environment, allowing you to experiment with blocks, themes, and plugins, build entire websites, and even create native apps running WordPress.

One of the key capabilities of WordPress Playground is the ability to embed interactive WordPress sites directly into your own sites through the use of an iframe:

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

As Zielinski wrote when he outlined the Playground philosophy, “WordPress Playground exists to make WordPress instantly accessible for users, learners, extenders, and contributors by building foundational software tools developers can use to create interactive, zero-setup, JavaScript applications with WordPress.”

It’s also possible to use WordPress Playground to run WordPress locally. Options for doing so include the WordPress Playground for VS Code plugin and the WP-NOW CLI tool.

You can also use the recently released Playground plugin to create a private instance of the WordPress Playground with a copy of your existing site. It copies all of the files and the database, and then sends them directly to your browser. This data isn’t saved anywhere, and it will only stick around until you close that browser tab.

Using the Query API With WordPress Playground

The Query API passes configuration parameters to the Playground URL. For example, entering https://playground.wordpress.net/?theme=frost&plugin=advanced-custom-fields&plugin=wp-migrate-db in your browser’s address bar will create a WordPress site with the Frost theme and the Advanced Custom Fields and WP Migrate Lite plugins installed and activated.

You can activate any theme or plugin in the WordPress repository by adding the theme or plugin parameter followed by the theme or plugin name. Similarly, you can switch the PHP and WordPress versions by adding the php and wp parameters followed by the version number. For example, https://playground.wordpress.net/?php=8.0&wp=6.0 will load Playground with PHP 8.0 and WordPress 6.0. There are more options available to configure WordPress, including blueprint-url, which loads a prebuilt Blueprint.

Using the Blueprint API With WordPress Playground

The Blueprint API is a low-code, JSON-based configuration file that serves as a build script for your Playground instance, creating an entire WordPress site. This gives you a much greater degree of control than the Query API alone. When using the Query API and Blueprint API together, Playground prioritizes the Blueprint-supported parameters, ignoring any conflicting Query API parameters.

The Blueprint API supports various options for installing plugins and themes, such as the official Plugins directory, any publicly accessible URL, or a file in your GitHub repository. You can also decide whether to activate them automatically or not.

The Blueprint editor is a work-in-progress tool that allows you to validate your Blueprint code in the browser. It starts you off with the basics, allowing you to build from there:

{
  "landingPage": "/wp-admin/",
  "phpExtensionBundles": [
    "kitchen-sink"
  ],
  "preferredVersions": {
    "php": "7.4",
    "wp": "5.9"
  },
  "steps": [
    {
      "step": "login",
      "username": "admin",
      "password": "password"
    }
  ]
}

To help write and validate Blueprints, Playground provides a JSON schema file that can be used to get autocompletion and validation.

Blueprints can posses a number of different properties:

• landingPage: The URL that the system will navigate to after the Blueprint has been executed.
• preferredVersions: An object that specifies the preferred versions of PHP and WordPress, defaulting to latest in both cases. Only major versions are accepted.
• phpExtensionBundles: An array of PHP extension bundles to load. The default choice is kitchen-sink. This installs several extensions, including gd, mbstring, iconv, openssl, libxml, xml, dom, simplexml, xmlreader, and xmlwriter. Alternatively, light doesn’t load any of those.
• features: An object that enables or disables certain features of the system. Using "networking": true enables networking support.
• steps: The array of steps to run when the Blueprint is loaded.

Using Blueprint Steps {using-blueprint-steps}

The steps object always includes at least one step property. These are further defined with parameters depending on the type of step. For example, the cp step is used to copy a file from one path to a different one, with parameters for the source path, fromPath, and the target, toPath:

   "steps": [
       {
           "step": "cp",
           "fromPath": "/wordpress/index.php",
           "toPath": "/wordpress/index2.php"
       }
   ]
}

There are over two dozen steps available for the Blueprint API. Creating a Playground instance this way is largely a matter of combining different steps to meet your specific needs. Blueprints provide much more control than the Query API alone, but for complete control, you need the JavaScript API.

Using the JavaScript API With WordPress Playground

The JavaScript API is a developer-oriented feature of WordPress Playground that gives you full control over your WordPress installation. To use the JavaScript API, you need an <iframe> element and the @wp-playground/client package.

WordPress Playground exposes two distinct APIs through two separate HTML files. You can dig into this more in the documentation, but in brief:

• remote.html: Runs and renders WordPress and exposes the JavaScript API, and won’t render any UI elements. This file is the only available endpoint for the PlaygroundClient class.
• index.html: Renders UI elements by embedding remote.html in an iframe. This file provides the Query API. It interacts with remote.html using PlaygroundClient.

With the JavaScript API, you can control the website inside the iframe using the Playground API Client, Blueprint JSON, or Blueprint functions. The JavaScript API client is exposed as window.playground for quick testing and debugging in both index.html and remote.html.

The PlaygroundClient Object

The PlaygroundClient object in WordPress Playground is an implementation of the UniversalPHP interface, which provides a consistent set of methods for running PHP code, customizing PHP.ini settings, and managing files and directories.

You can use the run() method to execute PHP code and retrieve the output. This method can be used in either code snippet mode or file mode. In code snippet mode, you pass a string containing PHP code to execute. In file mode, you specify the path to a PHP file, and the code in that file is executed. The request() method makes an HTTP request to the website, either serving a static file or dispatching it to the PHP runtime.

Wrapping Up

WordPress Playground offers a unique and powerful way to interact with the WordPress platform directly from the browser. The APIs provide a range of options to suit developers of all skill levels and needs, especially when you mix and match them.

For those just getting started, the Query API allows for quick and easy experimentation with WordPress functionality without writing any code. The Blueprint API then opens the door to more advanced customization, enabling developers to configure the Playground to their exact specifications. For the true WordPress power users, the JavaScript API grants complete control, allowing the creation of entirely new applications built on the WordPress foundation.

Have you used the WordPress Playground in a project? How was the experience? Let us know in the comments below!