A native AOT experiment with WordPress blocks, serialization, hooks and content. WordPress 7.1.4, Elephc 0.27.8, PHP profile 8.4, Linux x86_64.
The experiment uses nine original core files, with eight compatibility
patches, to build block parsing, serialization, hooks and rendering CLIs plus
an HTTP server. The formatting graph selects seven verified functions from the original
formatting.php; another five come from blocks.php. Documents, JSON block
trees and content inputs are processed at runtime.
The HTTP adapter, callback manifest and demo callbacks belong to this experiment.
This is a core subsystem port. The complete CMS bootstrap, database, plugin
discovery, themes, block rendering and wp-admin are outside the current profile.
Build and run directly on the host. The verified target is Linux x86_64. You need:
- The complete Elephc 0.27.8 SDK, including its runtime archives, on
PATH. elvm reads the repository's.elephc-version; runelvm install 0.27.8if needed. - Bash, Python 3.12 or newer,
patch, a C compiler/linker (cc) and GNU binutils (as,ar,strip). On Arch Linux these tools are provided bybase-devel,pythonandpatch; on Debian/Ubuntu usebuild-essential,binutils,python3andpatchwith a sufficiently recent Python. - Internet access for the first WordPress download and PCRE2 installation.
- PHP 8.4 or newer only for the differential reference tests. PHP is not required to compile or run the native executables.
From the repository root:
elephc --version
./scripts/build-elephc.shThe script verifies the downloaded sources and patches, installs the locked
PCRE2 dependency, and produces elephc/runtime/parse, elephc/runtime/hooks,
elephc/runtime/render, elephc/runtime/serialize and elephc/runtime/server.
It uses elephc from PATH; set
ELEPHC_BIN=/absolute/path/to/elephc to select another complete SDK.
On workstations with the author's build queue installed, the script uses it
automatically. The queue is optional on other machines.
The equivalent direct Elephc commands are:
python3 scripts/prepare-elephc.py
(
cd elephc/runtime
elephc native install --locked
elephc --php-version 8.4 --check server.php
elephc --php-version 8.4 parse.php
elephc --php-version 8.4 serialize.php
elephc --php-version 8.4 hooks.php
elephc --php-version 8.4 render.php
elephc --php-version 8.4 --web server.php
)The PHP profile is an explicit compiler setting. It does not require the reference PHP interpreter to be the same version.
./scripts/serve-elephc.shOpen http://127.0.0.1:9000/. The script starts the native server in the
foreground with one worker and a 64 KiB request body limit. Stop it with
Ctrl+C, and restart it after rebuilding.
You can also run the executable directly and choose a different port:
./elephc/runtime/server --listen 127.0.0.1:9001 --workers 1 --max-body-size 65536The demo, parsed blocks, hooks, rendered content and health endpoints are /,
/blocks, /hooks, /render and /health. /serialize accepts POST only.
No database or background service manager is required.
Parse your own document:
curl -sS http://127.0.0.1:9000/parse \
-H 'Content-Type: text/plain; charset=utf-8' \
--data-binary '<!-- wp:paragraph {"align":"center"} --><p>Hello!</p><!-- /wp:paragraph -->'The result is the WordPress block structure:
[{"blockName":"core/paragraph","attrs":{"align":"center"},"innerBlocks":[],"innerHTML":"<p>Hello!</p>","innerContent":["<p>Hello!</p>"]}]Use the native CLI directly:
./elephc/runtime/parse '<!-- wp:separator /-->'The native serializer uses five selected WordPress core functions:
serialize_block_attributes, strip_core_block_namespace,
get_comment_delimited_block_content, serialize_block and serialize_blocks.
It reconstructs a comment-delimited WordPress document from the block tree.
./elephc/runtime/parse '<!-- wp:paragraph {"align":"left"} --><p>Hello</p><!-- /wp:paragraph -->' > blocks.json
# Edit the JSON tree, for example changing attrs.align to "right".
./elephc/runtime/serialize < blocks.json
curl -sS http://127.0.0.1:9000/serialize \
-H 'Content-Type: application/json' --data-binary @blocks.jsonThe CLI defaults to blocks mode. It reads its input from stdin, or from its
second argument when provided. POST /serialize also defaults to a JSON block
list and returns the exact serialized document as text/plain; charset=utf-8.
Both interfaces support roundtrip mode to parse and serialize a raw document:
./elephc/runtime/serialize roundtrip '<!-- wp:separator /-->'
curl -sS 'http://127.0.0.1:9000/serialize?mode=roundtrip' \
--data-binary '<!-- wp:paragraph --><p>Hello</p><!-- /wp:paragraph -->'
./elephc/runtime/serialize attributes '{"label":"a--b <tag> & \"quote\""}'attributes mode returns the core's JSON encoding with substitutions for
characters that could interfere with HTML comments. The JSON list input uses
the same five fields returned by /parse: blockName, attrs, innerBlocks,
innerHTML and innerContent. The serializer reads innerContent, replacing
each null marker with the corresponding child from innerBlocks in order.
When editing HTML, update innerContent; innerHTML is parser metadata and
is not used to reconstruct the document.
The adapter checks required fields, content types, list layout, matching child
markers and a maximum of 64 block levels. Invalid input or an unknown mode
returns HTTP 400; the CLI writes a diagnostic to stderr and exits with 2.
JSON attributes must be encodable UTF-8 data. The native profile uses an
explicit JSON encoder bridge and raises an error on encoding failure;
WordPress's charset-recovery path in wp_json_encode is outside the profile.
The PHP oracle loads the unmodified core encoder and serialization functions.
Serialization follows WordPress normalization. Comment whitespace and JSON
formatting can change, and empty blocks become self-closing. Core considers
the content string "0" empty. Malformed nested documents can also change
structure across successive parse/serialize passes. Tests compare each stage
with original WordPress rather than assuming lossless or idempotent output.
The hooks profile runs WordPress's WP_Hook and the core plugin API. It
supports registration, priorities, callback removal, nested hooks, recursive
filters, mutation during an active hook, action/filter counters and the
all hook. The native profile initializes fresh hook tables; it does not
load an installed plugin directory.
./elephc/runtime/hooks priority 'Hello WordPress'
./elephc/runtime/hooks recursive 'Hello WordPress'
curl -sS http://127.0.0.1:9000/hooks
curl -sS 'http://127.0.0.1:9000/hooks?case=closure-capture&value=Hello'
curl -sS http://127.0.0.1:9000/filter --data-binary 'Hello WordPress'The default pipeline registers filters at priorities 5, 10 and 20, returning
Hello WordPress:early:middle:late. The full scenario inventory is in
tests/hooks-fixtures.json.
Closures, captured closures, first-class callables, instance/static methods,
invokable objects and the tested builtin strtoupper run through native
callable descriptors. Register application function names explicitly in the
AOT callback manifest before using string callbacks:
function my_title_filter(string $title): string {
return $title . '!';
}
WordPressHookCallbacks::register('my_title_filter', my_title_filter(...));
add_filter('the_title', 'my_title_filter');
$title = apply_filters('the_title', 'Hello WordPress');This registration belongs in the source entry point or its included application code, followed by a rebuild. It makes the function descriptor available to WordPress while retaining the original callback name as the registration and removal key. Direct closure callbacks do not need this name registration.
The source API also exposes apply_filters_ref_array and
do_action_ref_array; forwarding ordinary argument arrays is tested. Passing
reference-bound argument arrays into callbacks is outside this profile.
Closures that capture their own variables by reference are tested separately.
Nine unrelated APIs fail explicitly: deprecated-hook wrappers,
plugin_basename, wp_register_plugin_realpath, plugin_dir_path,
plugin_dir_url, and activation/deactivation/uninstall hook registration.
Preinitialized hook globals before bootstrap, arbitrary plugin discovery and
direct mutation of the public callback table are outside the profile.
WP_Hook iteration through foreach is tested; its next() adapter follows
the Iterator interface's void return contract.
The renderer runs the core shortcode engine and an explicit content-filter
pipeline: wpautop at priority 10, shortcode_unautop at priority 10, and
do_shortcode through a wrapper at priority 11. This is the selected pipeline,
not WordPress's complete default filter stack. It does not run do_blocks,
themes, KSES or installed plugins.
./elephc/runtime/render pipeline 'Welcome [greet name="Elephc"]'
./elephc/runtime/render shortcodes '[box]Hello [greet name="Ada"][/box]'
./elephc/runtime/render autop $'First paragraph\n\nSecond paragraph'
curl -sS http://127.0.0.1:9000/render
curl -sS http://127.0.0.1:9000/render --data-binary 'Welcome [greet name="Elephc"]'The default pipeline example returns:
<p>Welcome <span class="greeting">Hello Elephc</span></p>The source-defined demo registers greet, upper, box, counter, context
and several literal-tag aliases for regex checks. The core performs tag
selection, regex matching, attribute parsing, escaping, nesting and hook
dispatch. The demo callbacks supply their output; greet escapes its name
with PHP's htmlspecialchars.
GET /render renders the demo. POST /render accepts a raw UTF-8 body. Select
a mode with ?mode=shortcodes, autop, autop-no-br, strip or one of the
diagnostic modes listed in tests/render-fixtures.json. The CLI takes the mode
first and input second, and writes the exact rendered output. Diagnostic
attributes, inspect, context and registration modes produce JSON.
Shortcode processing uses ignore_html=true: shortcode-looking text inside
HTML attributes, comments and CDATA is not expanded. Attribute expansion with ignore_html=false
requires KSES and fails explicitly in this profile when encountered. Invalid
tag registration and invalid callbacks raise an exception instead of using
WordPress's translation/notice subsystem.
The renderer formats content and expands its registered shortcodes. It is not an HTML sanitizer. Same-tag nesting retains WordPress's original regex behavior; callbacks that process enclosed content explicitly invoke the core again.
python3 scripts/test-elephc.pyThe integration check compares 22 fixtures against the unmodified WordPress parser running on the host PHP interpreter. It compares the patched PHP implementation and the native CLI with that reference. 31 hook scenarios are independently compared with upstream PHP, patched PHP and the hooks CLI. Another 70 rendering fixtures compare original PHP, patched PHP and the rendering CLI. Another 58 serialization fixtures compare original PHP, patched PHP and native output, reparsed trees and the next serialization pass, with 22 invalid-input cases. The server checks all four corpora twice through one worker for 566 HTTP checks, including routing, body limits, response MIME types and request isolation.
| Request | Result |
|---|---|
GET / |
HTML demo, with a nested document parsed during the request |
GET /blocks |
Parsed demo as JSON |
GET /health |
Version/profile information, database: false |
POST /parse |
Parse a raw UTF-8 block document as JSON |
POST /serialize |
Serialize a JSON block tree as a WordPress document |
POST /serialize?mode=roundtrip |
Parse and serialize a raw block document |
| Invalid serialization input or mode | 400 |
GET /hooks?case=priority&value=Hello |
Run the selected hook scenario as JSON |
POST /filter |
Run a real priority filter pipeline on the raw request body |
GET /render |
HTML demo from the core content pipeline |
POST /render?mode=pipeline |
Format and expand request content as HTML |
POST /render?mode=attributes |
Parse shortcode attributes as JSON |
| Unknown render mode | 400 |
| Unknown hook scenario | 400 |
HEAD / |
200, empty body |
GET /missing |
404 |
GET /parse, POST /blocks |
405, appropriate Allow header |
| Request body over 64 KiB | 413 from the native transport |
The block fixture corpus covers Unicode, nested groups, void blocks, freeform text, JSON data, invalid JSON, missing and mismatched closers, and parser reuse. These checks establish the behavior of this corpus, not general WordPress or PHP compatibility. No performance comparison has been made.
The tests start a temporary native server on an available loopback port and
stop it automatically. Set PHP_BIN=/absolute/path/to/php to choose the
reference interpreter. The native host workflow was verified with PHP 8.5.12.
Hook coverage includes callback identity/removal, same-priority ordering,
zero and negative priorities, accepted argument counts, mixed values, live
insertion/removal, nested/recursive hooks, action context and counters,
all, argument-array forwarding and WP_Filter_Sentinel identity.
Rendering covers attribute syntaxes and C escapes, literal regex metacharacters
in tags, escaped and nested shortcodes, HTML boundaries, shortcode filters,
registration/removal, context cleanup, paragraph/newline behavior, protected
pre/script/style content and selected block-level HTML.
elephc/upstream.json pins the official
WordPress archive by SHA-256.
scripts/prepare-elephc.py downloads it into the ignored upstream/ directory
and extracts the complete original tree for inspection and reference checks.
These core classes and the hook API enter the compiled graph:
WP_Block_Parser
WP_Block_Parser_Block
WP_Block_Parser_Frame
WP_Hook
WP_Filter_Sentinel
wp-includes/plugin.php
wp-includes/shortcodes.php
seven selected functions from wp-includes/formatting.php
five selected functions from wp-includes/blocks.php
The three parser patches add explicit storage types, narrow parser frames,
replace a constructor passed directly to array_push, and adapt token capture
to Elephc's three-argument preg_match. The original regular expression and
parser state machine remain. Captures use numbered groups and byte offsets
are recovered from the matched suffix.
Two additional patches adapt WP_Hook and plugin.php. Priority-array
positions are explicit integers instead of PHP's hidden array pointers.
The upstream priority-resorting algorithm is retained, with differential
checks for additions and removals during dispatch. Typed object identity,
callback descriptor resolution and safe local copies for table updates
bridge the native storage/calling boundary. WP_Filter_Sentinel is copied
byte-for-byte without a patch.
The shortcode patch retains the original parser regex and adds explicit
types, closure adapters for regex callbacks, callback resolution and an explicit KSES
boundary. Small adapters cover the pinned SDK's missing preg_quote and
stripcslashes, array-search str_replace, typed string replacement maps and string-value
intersection of shortcode tag lists. Empty-subject guards avoid a pinned
native regex runtime crash while retaining the reference output.
They are exercised through the upstream differential corpus.
formatting.php and blocks.php are first patched as complete original files,
then reduced to their selected functions using byte ranges and per-function
hashes recorded in the manifest. Preparation verifies the complete patched source, each selected
fragment and each final generated module. This selection avoids importing the
unrelated formatting/UTF-8/bootstrap graph. Builds still require no PHP
interpreter; PHP was used only to identify function ranges during maintenance
and is needed for reference tests.
Original source, patch and generated source SHA-256 hashes are checked before
compilation. Patches apply with zero fuzz to an isolated, generated
elephc/runtime/core/ tree. Original files remain untouched.
python3 scripts/prepare-elephc.py --check
python3 scripts/test-clean-room.pyThe clean-room check exports maintained source files into a temporary directory, downloads a fresh WordPress archive, applies the patches, compiles all five executables and repeats the reference/HTTP checks. It reuses the installed SDK and native dependency cache, and removes its export when finished. PCRE2 10.47 is pinned in the native manifest and lockfile.
./scripts/check-upstream.shThis diagnostic intentionally returns 1 on Elephc 0.27.8. It checks four
unmodified source paths without executing them:
- Standard bootstrap: conditional
ABSPATHdefinition prevents resolving a subsequent include path. SHORTINITwithABSPATHdefined in advance:compat-utf8.phpcontains unsupportedgotostatements and labels.- Original standalone parser: unsupported
preg_matcharguments and stack object/storage inference prevent compilation. - Original hook API: a comma-separated static declaration blocks parsing; splitting it exposes type/storage and callback compatibility work.
These are observed first blockers, not an exhaustive compatibility audit. No diagnostic starts an installation or connects to a database.
elephc/probes/regex-empty-subject.php separately reproduces a native runtime
crash on an empty preg_replace subject. It is excluded from normal builds and
verified application tests. Compile a copy inside a native project with the
locked PCRE2 manifest and lockfile. The content profile has explicit empty-input
guards and passes the empty-input differential fixtures.
See the porting log and patch maintenance notes. WordPress and this experiment are distributed under GPL-2.0-or-later.