WordPress Playground public API allows you to run and control an entire WordPress stack in your browser. You can use it to build an entirely new kind of a web app, like an in-browser WordPress IDE we built at CloudFest Hackaton 2023. In this post, you will learn how to get started.
First, create the public API client
WordPress Playground public API client gives you control over a WordPress Playground instance displayed in a specific <iframe> element. Since everything happens in the browser, there is no network-based REST API. The term API here refers to a set of JavaScript functions available for you to call.
To create a new API client, use the connectPlayground function from the @wp-playground/client npm package:
These few lines are all you need to set up a controllable WordPress instance.
Starting a new WordPress Playground application
You can use the code snippet above almost verbatim on a vanilla HTML page. You don’t need an advanced setup, webpack, and even npm. Here’s a simple HTML file that would do the trick:
<!DOCTYPE html>
<iframe id="wp" style="width: 1200px; height: 800px"></iframe>
<script type="importmap"> { "imports": { "@wp-playground/client": "https://unpkg.com/@wp-playground/client/index.js" } } </script>
<script type="module">
import { connectPlayground, login } from '@wp-playground/client';
const client = await connectPlayground(
document.getElementById('wp'),
{ loadRemote: 'https://playground.wordpress.net/remote.html' }
);
await client.isReady();
await login(client, 'admin', 'password');
await client.goTo('/wp-admin/post-new.php');
</script>You can paste it on jsfiddle.net and, after a short loading, you will see WordPress post editor!
Manage the virtual filesystem
With an API client you have full power over the embedded site. You can, for example, create and open a new PHP file. It’s safe and isolated from your actual hard drive – WordPress Playground uses a virtual in-memory filesystem:
Feel free to use the code editor above to play with other methods like client.readFileAsText(path), client.readFileAsBuffer(path), client.isDir(path), and client.fileExists(path).
The API client is built with postMessage()
The API client communicates with the iframed remote.html file using postMessage(). Calling any function on the client object posts a message to remote.html, which then performs the actual function call and posts the return value back to the top-level window. Sounds cumbersome? That’s precisely why the API client hides that complexity!
Request PHP files programmatically
The iframe renders WordPress pages by calling the request method – you can also call it directly to send a custom HTTP request. It’s useful for submitting forms, e.g. to log the user in:
Despite its name, request() doesn’t actually trigger a fetch() request. Instead, it dispatches a request like a PHP server would: it prepares $_SERVER, $_POST, and other superglobals. Then, it runs the requested PHP script. Your web browser never gets to process the response cookies, but that’s fine – the API keeps track of any setcookie headers internally.
The request() method is just a convenience wrapper. It calls the lower-level run() method and provides lots of raw information like the HTTP host, protocol, or the absolute path of the executed script.
While run() isn’t ergonomic for dispatching requests, it’s handy for running PHP code snippets. Try this snippet in the code editor above:
const result = await client.run({
code: `<?php echo "Hello, world";`
});
// Check your browser's devtools:
console.log( result.text );Now you’re ready to build a new app!
You’ve just learned all you need to get started! If you’d like to learn even more, visit the GitHub repository and the documentation site. You’re also very welcome to ask any and all questions in the comments under this post. And if you don’t have any – great! Go and build an amazing app! 🙂