Description

With so many API changes recently merged, the current documentation is largely outdated. Let's revamp it with specific use-cases in mind. I'd like to directly answer questions like:

• Getting started
  • Sales pitch
    • WordPress Playground allows you to...
    • A few examples what people built
    • A blurb of what you can build
    • 1 minute code example with jsfiddle (or so) link
  • Table of contents of the entire doc site
  • Contributing (summary + link to a separate section)
• How do I use WordPress Playground to... (link to specific pages that bring the tiny bits of knowledge together)
  • ...start a site with a specific plugins, themes, starter content, and a WP or PHP version? (Document "How to install a plugin" #198, [Import/export] Support WXR, WXZ, and full-site import and export #209)
  • ...showcase my plugin or theme? (install a plugin, import starter content, set WP and PHP version)
  • ...control the embedded website?
  • ...provide interactive code snippets?
  • ...preview pull requests from my repo?
  • ...setup a development environment without installing Apache or MySQL? (wp-now, VScode extension)
  • ...test my plugin on different WordPress and PHP versions?
  • ...use my own Progress Bar?
  • ...(what else?)
• Tech details: How to embed and control WordPress Playground in my web app?
  • A brief glimpse of all the different methods. Direct links. Enourage to stop and learn about the mental model first.
  • Mental model: Endpoints, iframes, inter-iframe communication
    • Choose your endpoint: index.html vs remote.html
    • Inter-iframe communication Comlink.js inwards, postMessage relay outwards.
  • APIs (each with a discoverable list of methods and usage examples; ideally autogenerated from code so that it doesn't have to be kept in sync manually)
    • Easy: Query String API
    • Easy+ Blueprints
    • Medium: PlaygroundClient
• How does WordPress Playground work under the hood?
  • Reuse these existing materials to write this section:
    • High-level overview at web.dev
    • Existing doc pages: (PHP in JS, PHP in the browser, WP in the browser
    • Initial wp.org announcement
  • SQLite vs MySQL, Status update on the SQLite project, SQLite support via a MySQL parser
  • Bundling WordPress on the web
• How to develop PHP.wasm?
  • Mental models explained:
    • PHP->WASM Build pipeline (Dockerfile, Emscripten, SIDE_MODULES, Emscripten extensions, Filesystems, custom C patches in Playground)
    • php_wasm SAPI
    • Async calls via Asyncify, [JSPI]
    • Networking proxy and its technical limitations on the web vs in CLI(Ship the JSPI kitchen-sink build to Chrome users #134) possible in the future
  • Actual how to questions. How to:
    • Build with a new PHP extension
• Contributing
  • You don't need to know wasm. Wasm stuff make for 1% of this repo (I just made up this figure lol).
  • How to get started – "good first issues," JavaScript issues etc
  • GPL Licensing – boring stuff but important to keep in mind
  • How to...
    • Add a new package to the repo? (use NX generators, the most useful ones are...)
    • Set up a fast npm run dev command? (don't use rollup, reuse existing Vite configs)
    • Release a package for both web and Node.js? (build both .cjs and .esm, add a test:esmcjs executor to your package)
  • Overall guidelines
    • New APIs
      • Don't build new APIs unless many people ask for them
      • Don't make new APIs stable on day one, be prepared to scrape them and redo many times over
  • For core committers
    • Releasing npm packages (current vs next, keep the official remote.html working)