Automatically bootstrap interactive PHP snippets

[sirreal]

Summary

• automatically add the WordPress bootstrap preamble to exported interactive PHP snippets
• let documentation authors omit <?php and require '/wordpress/wp-load.php'; from examples
• normalize snippets that already contain an opening tag or the full preamble without duplicating either

Follow-up to #258

Context

This follows up on feedback from the review of #258 and the subsequent default-Blueprint discussion.

Interactive snippets execute as standalone PHP programs and need WordPress loaded, but the exporter previously copied fenced code verbatim. That forced every WordPress example to repeat execution boilerplate. The exporter now supplies that boilerplate while keeping the authored examples focused on the API being demonstrated.

Testing

• vendor/bin/phpunit
• 150 tests, 401 assertions

[sirreal]

I'm wondering if this is the right place to do this 🤔

Here, I do think we can inject <?php\n which seems like it will be necessary.

The web component has some configuration options and I think we should be able to configure it to require '/wordpress/wp-load.php'; before evaluating the snippet.

@adamziel Thoughts? A basic snippet should really not require 2 lines of bootstrap:

-<?php
-require '/wordpress/wp-load.php';
 echo esc_html( '<>' );

[sirreal]

The execution-environment question now has a proposed home in the Playground component itself: WordPress/wordpress-playground#4261 proposes a bootstrap attribute on <php-snippet> — hidden per-request setup PHP referenced from the embedding page, so the displayed snippet source stays free of environment boilerplate and readers' edits still run in a bootstrapped context.

That narrows this PR's scope to source normalization only:

• ensure extracted runnable snippets include a <?php opening tag;
• drop the WordPress preamble injection — loading WordPress becomes the theme's responsibility (it will emit a shared #wp-bootstrap element once per page and stamp bootstrap="#wp-bootstrap" on each snippet it renders).

[sirreal]

7.1 introduces the first usages:

https://github.com/WordPress/wordpress-develop/blob/05034a315158382ce33c4d3c6c74ddcd360c7d40/src/wp-includes/html-api/class-wp-html-tag-processor.php#L1181-L1194
https://github.com/WordPress/wordpress-develop/blob/05034a315158382ce33c4d3c6c74ddcd360c7d40/src/wp-includes/html-api/class-wp-html-processor.php#L5434-L5447

They both start with exactly:

<?php
require '/wordpress/wp-load.php';

I expect that to be redundant in the future (WordPress/wordpress-playground#4262). To support 7.1 and moving forward, we should recognize and strip that exactly that text at the start of the snippet, assuming playground support has landed for the implicit before script and the implicit PHP opener.

After 7.1 that special case can be removed and we'll expect snippets to just be PHP with no bootstrap necessary.

[adamziel]

WordPress/wordpress-playground#4262 landed. This PR is only needed until 4262 gets deployed to playground.wordpress.net, is there any reason to rush that or is after WCUS fine?

[sirreal]

There's no rush. The focus of this PR will changes and instead of adding anthing, it will remove <?php\nrequire… from snippets that include it in 7.1. We can expect future releases not to include the prefix.

In fact, I'll likely close this and create a new PR for that.