WordPress Playground is expanding beyond full WordPress sites. A recent set of changes makes Playground a useful lightweight PHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php runtime for documentation, tutorials, examples, and shareable demos.
The headline feature is the new <php-snippet> web component. It lets you embed runnable PHP examples in any web page with one script tag. Readers can edit the code, click Run, see the output in place, and experiment without installing PHP, configuring a server, or leaving the page.
This opens up a new way to teach WordPress and PHP APIs: examples can now be both readable and executable.
What changed
In an HTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. page, such as index.html, the new snippet embed is loaded from Playground:
<!-- index.html -->
<script
type="module"
src="https://playground.wordpress.net/php-code-snippet.js"
></script>
<php-snippet name="hello.php">
<script type="application/x-php">
<?php
echo "Hello from PHP " . phpversion();
</script>
</php-snippet>
This example is meant to be served as HTML, not evaluated as PHP on the server. If you paste the same markup into a .php template, the server-side PHP interpreter will see the raw <?php opening tag before the browser does. In that case, escape the opening tag as <?php, load the snippet from an external file with src, or otherwise make sure the browser receives the PHP code as literal text.
The component renders an editable, syntax-highlighted code block Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. with a Run button. When the reader clicks Run for the first time, Playground lazy-loads the runtime in a hidden iframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the userโs browser., runs the PHP, and displays the output below the snippet.
Multiple snippets on the same page can share the same runtime. That means a tutorial can include several examples without downloading and booting a separate PHP environment for each one.
WordPress APIs work too
By default, snippets run inside a real WordPress environment. That means examples can call WordPress APIs, not only plain PHP functions.
For example, a documentation page can demonstrate the HTML API An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.:
<php-snippet name="lazy-load-images.php">
<script type="application/x-php">
<?php
require '/wordpress/wp-load.php';
$html = '<article>
<img src="hero.jpg" alt="Hero">
<img src="inline.jpg" alt="Inline">
</article>';
$tags = new WP_HTML_Tag_Processor( $html );
while ( $tags->next_tag( 'img' ) ) {
$tags->set_attribute( 'loading', 'lazy' );
$tags->add_class( 'responsive' );
}
echo $tags->get_updated_html();
</script>
</php-snippet>
That changes the role of code examples in WordPress documentation. Instead of asking readers to copy code into a local site, the example can run where they are already reading.
PHP-only mode
Not every example needs WordPress. For plain PHP language features, snippets can skip the WordPress download entirely:
<php-snippet name="just-php.php" wp="none">
<script type="application/x-php">
<?php
echo "PHP " . phpversion() . "\n";
echo "WordPress installed: " .
( file_exists( '/wordpress/wp-includes/version.php' ) ? 'yes' : 'no' );
</script>
</php-snippet>
Under the hood, this maps to the new Blueprint option:
{
"preferredVersions": {
"php": "latest",
"wp": false
}
}
When preferredVersions.wp is false, Playground boots PHP without downloading or installing WordPress. WordPress-specific Blueprint fields and steps are rejected, which keeps PHP-only examples explicit and predictable.
From demo page to documentation guide
The snippets work also moves beyond the original test/demo page. The PHP snippets guide is becoming the canonical reference for this feature, with live-rendered examples alongside copyable code.
That matters because the guide can show the feature in the same shape that authors will use it: basic embeds, precomputed output, selector-based snippets, WordPress snippets, pure PHP snippets, and option-by-option usage. The old demo page redirects readers to the guide, and the componentโs attribution link points there too.
How to use it
Add the module script once on the page, then place each example in a <php-snippet> element. The recommended pattern is to put PHP inside a child <script type="application/x-php"> element when the surrounding document is HTML, MDX, or another format that will deliver the PHP code to the browser unchanged:
<php-snippet name="site-title.php">
<script type="application/x-php">
<?php
require '/wordpress/wp-load.php';
update_option( 'blogname', 'Snippet Docs' );
echo get_bloginfo( 'name' );
</script>
<script type="text/expected-output">
Snippet Docs
</script>
</php-snippet>
The application/x-php wrapper is useful because browsers ignore unknown script types. That lets authors include PHP strings containing HTML without escaping every < character.
For very short examples, inline text works too, but the PHP opening tag must be escaped:
<php-snippet name="sum.php" expected-output="42">
<?php echo 20 + 22;
</php-snippet>
Show output before Run
Use expected output when you want the result visible immediately. The placeholder is replaced by the real runtime output after the reader clicks Run.
<php-snippet name="precomputed.php">
<script type="application/x-php">
<?php
echo "2 + 2 = " . ( 2 + 2 );
</script>
<script type="text/expected-output">
2 + 2 = 4
</script>
</php-snippet>
For one-line output, use the expected-output attribute:
<php-snippet name="ready.php" expected-output="Ready">
<script type="application/x-php">
<?php echo "Ready";
</script>
</php-snippet>
Prepare examples with a Blueprint
Use blueprint when snippets need to be set up before the PHP code runs. The Blueprint can create files, add a mu-plugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party., configure options, install plugins, or prepare sample content.
<script id="setup-blueprint" type="application/json">
{
"steps": [
{
"step": "writeFile",
"path": "/wordpress/wp-content/mu-plugins/helpers.php",
"data": "<?php\nfunction docs_greet($name) { return 'Hello, ' . $name; }\n"
}
]
}
</script>
<php-snippet name="greeting.php" blueprint="setup-blueprint">
<script type="application/x-php">
<?php
require '/wordpress/wp-load.php';
echo docs_greet( 'Ada' );
</script>
<script type="text/expected-output">
Hello, Ada
</script>
</php-snippet>
The blueprint attribute accepts an element id or a CSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. selector. Use <script type="application/json"> for the Blueprint because its contents are treated as raw text, which keeps embedded PHP strings predictable.
Load PHP from another file
Use src when the PHP source should live in a separate file:
<php-snippet
name="external-example.php"
src="/snippets/external-example.php"
expected-output="Loaded from an external file"
></php-snippet>
The URL A specific web address of a website or web page on the Internet, such as a websiteโs URL www.wordpress.org resolves from the page that contains the snippet. If the PHP file is hosted on another origin, that server needs to allow cross-origin access. Use a Blueprint instead when the example needs support files, plugins, options, or other setup.
Pin versions or self-host the runtime
The default PHP version is 8.4, and the default WordPress version is latest. Use the php and wp attributes when the example depends on a specific version:
<php-snippet name="wp-version.php" php="8.4" wp="6.8">
<script type="application/x-php">
<?php
require '/wordpress/wp-load.php';
echo get_bloginfo( 'version' );
</script>
</php-snippet>
Most pages should use the hosted runtime from https://playground.wordpress.net. For local development, self-hosting, or pinned infrastructure, use playground-origin:
<php-snippet
name="local-runtime.php"
playground-origin="http://localhost:5400"
>
<script type="application/x-php">
<?php
echo phpversion();
</script>
</php-snippet>
More control for authors
The snippet component includes a few authoring tools that make it practical for real documentation:
- Snippets are editable by default, so readers can change the code before running it.
- Use
Ctrl+Enter or Cmd+Enter to run a focused editable snippet from the keyboard.
- Use
readonly for runnable examples that should stay locked.
- Use
editable="false" as a compatibility alias for older examples that already use that pattern.
- Use
src to load PHP from a separate file.
- Use
expected-output or a <script type="text/expected-output"> child to show expected output before the reader clicks Run.
- Use
runnable="false" for syntax-highlighted examples that should not execute.
- Use
php and wp attributes to choose the PHP and WordPress versions for a snippet.
- Use a shared Blueprint when multiple snippets need the same setup, such as a mu-plugin, site option, or file.
That last point is especially useful for longer tutorials. A page can define one JSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. Blueprint and point several snippets at it. Playground boots the shared environment once, then each snippet runs against the same prepared runtime.
Runtime sharing and troubleshooting
The first run clicks on a page, loads the Playground client, creates a hidden iframe, boots PHP, and installs WordPress unless the snippet uses wp="none". Later runs reuse an existing runtime when playground-origin, php, wp, and the resolved Blueprint JSON all match.
That sharing keeps related snippets fast while still isolating examples that need a different PHP version, WordPress version, or setup Blueprint.
If a snippet does not render, check that the module script is loaded and that the browser supports custom elements. If Run never finishes, open DevTools and look for failed requests to remote.html, PHP .wasm files, WordPress zip files, Blueprint resources, or cross-origin src files.
Sites with a strict Content Security Policy need to allow the module script and hidden iframe from https://playground.wordpress.net, plus the runtime assets that Playground downloads. For stricter environments, self-host the snippet script and point playground-origin at that deployment.
Standalone PHP Playground
For full-page examples, Playground also includes a standalone PHP editor:
playground.wordpress.net/php-playground.html
It provides a side-by-side editor and preview with PHP and WordPress version selectors. The current code and version choices are encoded in the URL fragment, so examples can be shared as links or embedded in an iframe.
Use the standalone editor for a single larger demo. Use <php-snippet> when a post, handbook page, or tutorial needs several small runnable examples inline.
Why this matters
Runnable snippets make Playground useful in a new layer of the WordPress learning experience.
For doc authors, it reduces the gap between explanation and verification. A reader can run the example immediately.
For contributors, it creates a low-friction way to demonstrate WordPress APIs, PHP behavior, Blueprint setup steps, or bug reproductions.
For learners, it removes the setup barrier. They can try PHP and WordPress code in the browser first, then move to a local environment when they are ready.
This also broadens the meaning of Playground. It is still a full WordPress runtime in the browser, but it can now act as a small, embeddable PHP execution layer for the web.
Try it and share feedback
Try the snippet embed in a local HTML file, a documentation page, or a tutorial draft:
<script
type="module"
src="https://playground.wordpress.net/php-code-snippet.js"
></script>
For deeper examples, see the new PHP snippets guide in the Playground documentation:
PHP code snippets and embeds
Feedback is welcome in the #playground channel on Making WordPress Slack or in the WordPress Playground GitHub repository.
