wp-php-toolkit/html

Expose PHP fallback APIs from native wrappers

Expose PHP fallback APIs from native wrappers

Expose PHP fallback APIs from native wrappers

Expose PHP fallback APIs from native wrappers

Fix native wrapper autoload without extension

What it does

Changes the public PHP classes to progressively use the native extension
with no API-consumer burden.

When the extension is installed and the native class advertises
supports_public_api(), the public PHP class resolves to the native
implementation. Otherwise it falls back to the moved PHP implementation.

Implemented wiring:

The native wrapper files are intentionally tiny:

components/DataLiberation/URL/class-nativeurlintextprocessorwrapper.php:
5 lines

• components/HTML/class-wp-html-native-processor-wrapper.php: 9 lines
• components/HTML/class-wp-html-native-tag-processor-wrapper.php: 9
  lines
• components/XML/class-xmlnativecursorprocessor.php: 5 lines

Rationale

The public class names should remain stable for consumers. Installing
the native extension should be a progressive upgrade, not a new API they
have to opt into.

This PR keeps PHP responsible for loading and fallback only. Parser
behavior belongs to the Rust classes already merged from #276 or to the
moved PHP fallback classes.

Implementation

The moved PHP implementations live under component PHP/ paths. Public
loader files choose the native class only when all of these are true:

! defined( 'WP_NATIVE_APIS_DISABLE_DEFAULTS' ) || ! WP_NATIVE_APIS_DISABLE_DEFAULTS
class_exists( $native_class, false )
method_exists( $native_class, 'supports_public_api' )
$native_class::supports_public_api()

There are no per-component WP_NATIVE_APIS_ENABLE_* switches. Tests and
benchmarks can use the single global opt-out constant when they need to
force fallback behavior.

The benchmark harness now tolerates unsupported PHP fallback rows
instead of aborting the run, while --require-native still fails if any
native implementation row is unavailable.

Benchmarks

Benchmark run:
https://github.com/WordPress/php-toolkit/actions/runs/25988013187

Command:

php -d extension=extensions/native-apis/target/release/libwp_native_apis.so \
  bin/benchmark-native-apis.php \
  --iterations=100 \
  --mode=both \
  --disable-native-defaults \
  --require-native

Representative PHP-fallback vs native rows:

The same run also completed all native fused/chunked benchmark rows for
HTML, XML, and URL-in-text with --require-native enabled.

Testing instructions

Local checks run for the benchmark harness fixes:

php -l bin/benchmark-native-apis.php

Previously run locally before the #276 rebase:

php -l components/HTML/class-wp-html-native-tag-processor-wrapper.php
php -l components/HTML/class-wp-html-native-processor-wrapper.php
php -l components/DataLiberation/URL/class-nativeurlintextprocessorwrapper.php
php -l components/XML/class-xmlnativecursorprocessor.php
php -l components/XML/class-xmlprocessor.php
php -l components/HTML/class-wp-html-tag-processor.php
php -l components/HTML/class-wp-html-processor.php
php -l components/DataLiberation/URL/class-urlintextprocessor.php
vendor/bin/phpunit components/HTML/Tests/NativeHTMLConformanceTest.php
vendor/bin/phpunit components/XML/Tests/NativeXMLConformanceTest.php
vendor/bin/phpunit components/DataLiberation/Tests/URLInTextProcessorTest.php components/DataLiberation/Tests/URLInTextProcessorWHATWGComplianceTest.php components/DataLiberation/Tests/WPURLTest.php
vendor/bin/phpcs --standard=phpcs.xml components/DataLiberation/URL/class-nativeurlintextprocessorwrapper.php components/DataLiberation/URL/class-urlintextprocessor.php components/HTML/class-wp-html-native-processor-wrapper.php components/HTML/class-wp-html-native-tag-processor-wrapper.php components/HTML/class-wp-html-processor.php components/HTML/class-wp-html-tag-processor.php components/XML/class-xmlnativecursorprocessor.php components/XML/class-xmlprocessor.php components/HTML/Tests/NativeHTMLConformanceTest.php components/XML/Tests/NativeXMLConformanceTest.php
git diff --check

GitHub Actions is the authoritative extension build/load check for this
PR because this local machine does not have php-config.

What it does

Moves the existing public API implementation files to *php* sidecar
filenames with no line changes.

This is intentionally only a file-move PR. It does not add public
loaders, native wrapper classes, or behavior changes; those stay in the
stacked PR #271.

Rationale

This gives reviewers a clean baseline where GitHub shows the large
implementation files as renames before #271 adds the native integration
and loader changes.

Implementation

Moved these files at 100% similarity:

• components/HTML/class-wp-html-tag-processor.php ->
  components/HTML/class-wp-html-php-tag-processor.php
• components/HTML/class-wp-html-processor.php ->
  components/HTML/class-wp-html-php-processor.php
• components/XML/class-xmlprocessor.php ->
  components/XML/class-phpxmlprocessor.php
• components/DataLiberation/URL/class-urlintextprocessor.php ->
  components/DataLiberation/URL/class-phpurlintextprocessor.php

The class names are deliberately unchanged in this PR so the diff
remains move-only.

Testing instructions

composer dump-autoload
php -l components/HTML/class-wp-html-php-tag-processor.php components/HTML/class-wp-html-php-processor.php components/XML/class-phpxmlprocessor.php components/DataLiberation/URL/class-phpurlintextprocessor.php
vendor/bin/phpunit components/XML/Tests/
vendor/bin/phpunit components/DataLiberation/Tests/URLInTextProcessorTest.php
vendor/bin/phpunit components/DataLiberation/Tests/MarkupProcessorConsumerTest.php components/DataLiberation/Tests/HTMLEntityReaderTest.php
vendor/bin/phpunit components/Markdown/Tests/MarkdownConsumerTest.php
git diff origin/trunk...HEAD --check

Summary

The toolkit now documents itself using only its own runtime and its
own structured-data parsers. No Python in CI; no hand-rolled regex over
markdown or HTML.

What changed

Parsers

Behavioural parity

• 87/87 snippets match their captured stdout. The PHP normalizer
  mirrors the Python regex set 1:1, so existing expected-output blocks
  stay valid.
• docs/reference/*.html render correctly: 9 <php-snippet> + 9
  fallback + 9 expected-output triples on html.html, 4 pitfall callouts
  (the bold-lead pattern is preserved), see-also list intact.
• --update verified end-to-end:
• When an expected-output block has drifted, the rewritten content is
  byte-for-byte the original.
• When no expected-output exists for a snippet, --update inserts a
  fresh block in the right place; resulting README is byte-identical to
  one with the block authored manually.

Frontmatter format change: see_also is a proper YAML list

# Before (repeated keys — not standard YAML)
see_also: a | A | reason
see_also: b | B | reason

# After
see_also:
  - a | A | reason
  - b | B | reason

Webuni\FrontMatter\FrontMatter correctly types it as a sequence; any
frontmatter-aware tool reading the README sees the same shape. All 18
component READMEs migrated.

Workflows simplified

• snippet-tests.yml drops the actions/setup-python step.
• docs.yml swaps python3 bin/build-reference.py for php bin/build-reference.php.

Remaining preg_* calls (all on plain text, not HTML)

• slugify() — heading text → URL-safe slug.
• normalize() — scrubs noise from snippet stdout (tempfile paths, git
  hashes, timestamps).
• One pattern in run-snippets that matches the require '...autoload.php'; line in the snippet's PHP source to inject the
  local-prelude polyfill.

These operate on plain strings, not HTML, so they're not what the "no
regex over HTML" rule was about.

Test plan

• Verify docs snippets workflow passes (87/87).
• Deploy docs to GitHub Pages runs cleanly on push to trunk.
• Local preview: bash bin/build-docs-bundle.sh && php bin/serve-docs.php — http://localhost:8787 renders all reference pages
  with snippets.
• php bin/run-snippets.php --update (no-op, no drift) leaves all
  READMEs untouched.

Summary

The toolkit now documents itself using only its own runtime and its
own structured-data parsers. No Python in CI; no hand-rolled regex over
markdown or HTML.

What changed

Parsers

Behavioural parity

• 87/87 snippets match their captured stdout. The PHP normalizer
  mirrors the Python regex set 1:1, so existing expected-output blocks
  stay valid.
• docs/reference/*.html render correctly: 9 <php-snippet> + 9
  fallback + 9 expected-output triples on html.html, 4 pitfall callouts
  (the bold-lead pattern is preserved), see-also list intact.
• --update verified end-to-end:
• When an expected-output block has drifted, the rewritten content is
  byte-for-byte the original.
• When no expected-output exists for a snippet, --update inserts a
  fresh block in the right place; resulting README is byte-identical to
  one with the block authored manually.

Frontmatter format change: see_also is a proper YAML list

# Before (repeated keys — not standard YAML)
see_also: a | A | reason
see_also: b | B | reason

# After
see_also:
  - a | A | reason
  - b | B | reason

Webuni\FrontMatter\FrontMatter correctly types it as a sequence; any
frontmatter-aware tool reading the README sees the same shape. All 18
component READMEs migrated.

Workflows simplified

• snippet-tests.yml drops the actions/setup-python step.
• docs.yml swaps python3 bin/build-reference.py for php bin/build-reference.php.

Remaining preg_* calls (all on plain text, not HTML)

• slugify() — heading text → URL-safe slug.
• normalize() — scrubs noise from snippet stdout (tempfile paths, git
  hashes, timestamps).
• One pattern in run-snippets that matches the require '...autoload.php'; line in the snippet's PHP source to inject the
  local-prelude polyfill.

These operate on plain strings, not HTML, so they're not what the "no
regex over HTML" rule was about.

Test plan

• Verify docs snippets workflow passes (87/87).
• Deploy docs to GitHub Pages runs cleanly on push to trunk.
• Local preview: bash bin/build-docs-bundle.sh && php bin/serve-docs.php — http://localhost:8787 renders all reference pages
  with snippets.
• php bin/run-snippets.php --update (no-op, no drift) leaves all
  READMEs untouched.