diff --git a/packages/docs/site/docs/main/guides/index.md b/packages/docs/site/docs/main/guides/index.md index 4555e909976..c92760a1e3b 100644 --- a/packages/docs/site/docs/main/guides/index.md +++ b/packages/docs/site/docs/main/guides/index.md @@ -13,6 +13,10 @@ In this section we present a selection of guides that will help you to both work Embed editable, runnable PHP and WordPress examples in any web page with the `` web component. The guide covers custom Blueprints, expected output, pure-PHP snippets, runtime sharing, and the standalone PHP Playground. +## [Run PHP frameworks in Playground](/guides/php-frameworks) + +Use Playground as a generic browser-based PHP runtime. This guide shows how to skip the WordPress download, load a bundled Symfony app with a Blueprint, and run it from a ``. + ## [WordPress Playground for Everyone](/guides/playground-for-everyone) Think Playground is only for developers? Think again. This guide shows how WordPress Playground helps beginners, site owners, and everyday users experiment safely — no technical expertise required. diff --git a/packages/docs/site/docs/main/guides/php-frameworks.md b/packages/docs/site/docs/main/guides/php-frameworks.md new file mode 100644 index 00000000000..cf2f12bc16b --- /dev/null +++ b/packages/docs/site/docs/main/guides/php-frameworks.md @@ -0,0 +1,185 @@ +--- +title: Run PHP frameworks in Playground +slug: /guides/php-frameworks +description: Use WordPress Playground as a browser-based PHP runtime for frameworks and apps that are not WordPress. +sidebar_class_name: navbar-build-item +--- + +import { PhpCodeSnippetExample } from '@site/src/components/PhpCodeSnippetLiveExample'; + +# Run PHP frameworks in Playground + +WordPress Playground is also a browser-based PHP runtime. WordPress is the +most common app it boots, but a Blueprint can skip the WordPress download, +write any PHP files into the virtual filesystem, and run a framework such as +Symfony. + +This guide shows the shape of that setup. Use it when you want a shareable demo, +a docs example, or a quick compatibility check for a PHP app that does not need +a server, database, Node.js, Sass, or a local Composer install. + +## What changes when you skip WordPress + +Set `preferredVersions.wp` to `false` in a Blueprint, or `wp="none"` on a +``. Playground still downloads PHP, mounts a writable filesystem, +runs Blueprint steps, and supports networking when `features.networking` is +`true`. It just does not download or boot WordPress. + +That makes Playground useful for generic PHP examples: + +- PHP libraries that need a real filesystem. +- Framework demos that can run behind `public/index.php`. +- Documentation snippets that should execute in the browser. +- Reproducible bug reports for PHP code that is not WordPress-specific. + +## Try a Symfony app + +The example below uses a Blueprint to download and unzip a bundled Symfony app +into `/app`. Then a `` boots the Symfony kernel and renders the +dashboard route. The app's Composer dependencies include the WordPress HTML API, +so the snippet can read the `

` with `WP_HTML_Processor` without installing or +booting WordPress. + + + +Here is the complete embed: + + + +```html + + + + + + + + +``` + + + +The same app is also available as a full Playground page: + +[Open the Symfony Package Radar demo](https://playground.wordpress.net/?blueprint-url=https%3A%2F%2Fwordpress.github.io%2Fblueprints%2Fblueprints%2Fsymfony-package-radar%2Fblueprint.json) + +## Package the app as a ZIP + +For framework demos, prefer a ZIP that already contains `vendor/`. That keeps +the Playground startup path short and avoids asking every visitor to wait for +Composer, Git, and package registry downloads. The Symfony demo uses that path to +bundle both Symfony and a Composer-installed copy of the WordPress HTML API; it +still does not include a WordPress install. + +For snippets or CLI runs, a small Blueprint can install the app into `/app` with +one step: + +```json +{ + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "landingPage": "/symfony-package-radar/public/index.php", + "preferredVersions": { + "php": "8.4", + "wp": false + }, + "features": { + "networking": true + }, + "steps": [ + { + "step": "unzip", + "zipFile": { + "resource": "bundled", + "path": "./symfony-package-radar.zip" + }, + "extractToPath": "/app" + } + ] +} +``` + +Use `bundled` resources when the ZIP ships next to `blueprint.json`, or use a +`url` resource when the ZIP is hosted separately. See [Blueprint bundles](/blueprints/bundles) +for packaging details. + +For a full-page Playground website, use a Blueprint like the gallery demo. It +adds a tiny router at the Playground document root so the Symfony `public/` +directory can respond to browser requests. + +## Keep the demo browser-friendly + +A Playground-hosted framework demo works best when it: + +- Does not require a long-running background process. +- Stores generated files under the virtual filesystem. +- Avoids native extensions that are not compiled into PHP.wasm. +- Avoids frontend build steps at runtime. +- Keeps network calls optional or resilient, because browsers may require CORS + proxying for third-party services. + +Those constraints still leave plenty of room for real framework behavior: +controllers, routing, dependency injection, templates, forms, HTTP clients, and +plain PHP libraries all work when their PHP dependencies are available. diff --git a/packages/docs/site/sidebars.js b/packages/docs/site/sidebars.js index 821d62fa8cf..0552b70ab1f 100644 --- a/packages/docs/site/sidebars.js +++ b/packages/docs/site/sidebars.js @@ -46,6 +46,7 @@ const sidebars = { }, items: [ 'main/guides/php-code-snippets', + 'main/guides/php-frameworks', 'main/guides/agent-skill-wp-playground', 'main/guides/wordpress-native-ios-app', 'main/guides/for-plugin-developers', diff --git a/packages/docs/site/src/components/PhpCodeSnippetLiveExample.examples.ts b/packages/docs/site/src/components/PhpCodeSnippetLiveExample.examples.ts index c6a37a6d1d9..e706e80fefc 100644 --- a/packages/docs/site/src/components/PhpCodeSnippetLiveExample.examples.ts +++ b/packages/docs/site/src/components/PhpCodeSnippetLiveExample.examples.ts @@ -187,6 +187,76 @@ echo get_bloginfo( 'version' ); +`, + symfonyBlueprint: String.raw` + + + + `, illustration: String.raw`