Export method code snippets

[adamziel]

What it does

Exports runnable PHP examples from DocBlocks as doc.code_snippets, replaces each PHP fence in doc.long_description with an inline placeholder (<!-- wp-parser-code-snippet:N -->), and stores the snippet metadata during import. The theme renders each placeholder as a runnable snippet in place, so a snippet stays between the surrounding prose instead of collapsing to the end of the description.

A DocBlock can pair a php fence with expected-output and optional setup Blueprint data:

```php
<?php
echo 'Hello';
```

```expected-output
Hello
```

For reusable setup, define a named setup Blueprint once and reference it from multiple PHP fences:

```setupblueprint shared-greeting
{"steps":[{"step":"writeFile","path":"/wordpress/wp-content/mu-plugins/shared.php","data":"<?php ..."}]}
```

```php blueprint=shared-greeting
<?php
require '/wordpress/wp-load.php';
echo docs_shared_greeting( 'first' );
```

```php setup-blueprint=shared-greeting
<?php
require '/wordpress/wp-load.php';
echo docs_shared_greeting( 'second' );
```

File-level setup Blueprints are inherited by functions, classes, and methods in that file, so one setup definition can be reused by several examples.

How the export JSON changes

Only PHP fences move; a plain fence (no language) is left untouched. Here is the same DocBlock — one plain fence and one php example — parsed by master versus this branch (the function's doc, HTML abbreviated):

 "doc": {
   "description": "Greets a person.",
-  "long_description": "…<pre><code>$greeting = docs_greet( $name );</code></pre>… <pre><code>echo docs_greet( $name );</code></pre> <pre><code>Hello, World!</code></pre>",
+  "long_description": "…<pre><code>$greeting = docs_greet( $name );</code></pre>… <!-- wp-parser-code-snippet:0 -->",
+  "code_snippets": [
+    { "type": "php-code-snippet", "code": "<?php\necho docs_greet( $name );", "expected_output": "Hello, World!" }
+  ],
   "tags": [ /* @param, @return — unchanged */ ]
 }

The plain $greeting fence stays in long_description; the php fence becomes a positioned placeholder plus a code_snippets entry.

Screenshot

Actual wporg-developer render from an imported fixture using this parser branch plus WordPress/wporg-developer#567. The second and third examples share a named setup Blueprint.

Try it in WordPress Playground

WP_HTML_Tag_Processor's usage docs — prose interleaved with both plain code fences and runnable PHP fences — imported into the built wporg-developer-2023 stack. (These are minimal Playgrounds, so the global theme styling is absent; the snippet rendering is what they demonstrate.)

• ▶ With WordPress/wporg-developer#567 — the plain fences render inline as code blocks and each PHP fence renders as a runnable <php-snippet>, all in place: code block → snippet → "Finding tags" → code block → snippet.
• ▶ On the stock theme, without #567 — the plain fences still render as code blocks (proving they are not removed), the PHP placeholders stay as invisible HTML comments, no runnable snippets appear, and there are no PHP errors.

Rationale

WordPress.org docs need structured data for php-code-snippet, with JSON as the intermediate format. Exporting code, expected_output, and setup Blueprint data avoids reverse-parsing rendered HTML later.

Replacing each PHP fence with an inline placeholder — rather than dropping it — keeps the theme from rendering duplicate examples while preserving the snippet's position: the plain code fence disappears, and the runnable snippet renders exactly where it appeared in the prose.

Backward compatibility

Safe to land before WordPress/wporg-developer#567. A theme that doesn't read the new post meta ignores it, and the placeholders are invisible HTML comments, so pages render cleanly with no PHP errors (see the stock-theme Playground above). Nothing visible is removed today either: only php-tagged fences are converted, and a scan of wordpress-develop/src (1,858 files) finds zero php-tagged fences in WordPress's own docs — the few that exist live only in bundled libraries such as PHPMailer/ and php-ai-client/. Plain code fences, which core does use, are left untouched. #567 is needed only to render the new convention (e.g. WordPress/wordpress-develop#29).

Testing instructions

• Try the Playground links above.
• Confirm the CI passed.