Skip to content

README.md

Latest commit

 

History

History
104 lines (71 loc) · 4.36 KB

README.md

File metadata and controls

104 lines (71 loc) · 4.36 KB

WP MySQL Parser PHP Extension

wp_mysql_parser is an optional native PHP extension for the SQLite Database Integration project. It provides native implementations of the MySQL lexer/parser path used by the SQLite driver while keeping the pure-PHP implementation as the portable fallback.

When the extension is loaded before packages/mysql-on-sqlite/src/load.php, it registers native base classes used by the public WP_MySQL_Lexer and WP_MySQL_Parser wrappers. Without the extension, those public wrappers extend the pure-PHP implementations instead.

Published WASM build for Playground

Published WASM builds are listed on this repository's GitHub Pages site, with manifest links and a “Run in Playground” link for each release:

https://wordpress.github.io/sqlite-database-integration/

The current build is also available directly:

Use this Playground URL to load the extension and open the demo/benchmark page. The published manifest contains PHP 8.0 through 8.5 side modules, and CI checks that every side module imports only symbols exported by the matching Playground browser runtime.

https://playground.wordpress.net/?php=8.5&php-extension=https%3A%2F%2Fwordpress.github.io%2Fsqlite-database-integration%2Fwp_mysql_parser-wasm-extension%2Flatest%2Fmanifest.json&blueprint-url=https%3A%2F%2Fwordpress.github.io%2Fsqlite-database-integration%2Fblueprint.json

Build the native extension locally

Requirements:

  • Rust toolchain.
  • PHP development headers and php-config.
  • libclang, with LIBCLANG_PATH pointing at the directory containing the libclang shared library when auto-detection is not enough.
(
	cd packages/php-ext-wp-mysql-parser
	PHP_CONFIG="$(command -v php-config)" \
	LIBCLANG_PATH=/path/to/libclang \
	cargo build --release
)

On macOS, if the linker reports unresolved Zend/PHP symbols, add dynamic lookup linker flags:

(
	cd packages/php-ext-wp-mysql-parser
	RUSTFLAGS='-C link-arg=-undefined -C link-arg=dynamic_lookup' \
	PHP_CONFIG="$(command -v php-config)" \
	LIBCLANG_PATH=/path/to/libclang \
	cargo build --release
)

The resulting shared object is written under target/release/ as libwp_mysql_parser.so on Linux or libwp_mysql_parser.dylib on macOS.

From the repository root, load it for local verification or benchmarks:

php -d extension=/absolute/path/to/libwp_mysql_parser.so -m | grep wp_mysql_parser
php -d extension=/absolute/path/to/libwp_mysql_parser.so packages/mysql-on-sqlite/tests/tools/verify-native-parser-extension.php

Benchmarks

Run the pure-PHP lexer/parser benchmarks:

php packages/mysql-on-sqlite/tests/tools/run-lexer-benchmark.php --json
php packages/mysql-on-sqlite/tests/tools/run-parser-benchmark.php --json

Run the same parser benchmark with the native extension loaded:

php -d extension=/absolute/path/to/libwp_mysql_parser.so packages/mysql-on-sqlite/tests/tools/run-parser-benchmark.php --json

Compare the pure-PHP lexer with the native extension lexer in one process:

php -d extension=/absolute/path/to/libwp_mysql_parser.so packages/mysql-on-sqlite/tests/tools/run-native-extension-benchmark.php
php -d extension=/absolute/path/to/libwp_mysql_parser.so packages/mysql-on-sqlite/tests/tools/run-native-extension-benchmark.php --json

The GitHub Pages demo reads published benchmark data from:

https://wordpress.github.io/sqlite-database-integration/native-extension/benchmark.json

Latest local measurement (Apple Silicon macOS, PHP 8.4.5 CLI, 2026-05-26):

Benchmark Implementation Queries QPS Speedup
MySQL lexer Pure PHP 69,577 71,553 —
MySQL lexer Native extension 69,577 343,124 4.80x
MySQL parser Pure PHP 69,577 7,015 —
MySQL parser Native extension 69,577 108,354 15.45x

That file should be updated whenever a new extension build or benchmark environment is published.

PHP.wasm side-module build

The experimental PHP.wasm side-module build lives in wasm-spike/ and is verified in CI for PHP 8.0 through 8.5.

PHP 7.4 is not supported by this Rust WASM path. The build uses ext-php-rs 0.15, which depends on PHP 8 Zend APIs and does not compile against PHP 7.4 headers.