HTML to Blocks Converter

A legacy WordPress plugin and Composer package that exposes the historical html_to_blocks_* facade while delegating canonical raw HTML conversion to Blocks Engine.

New consumers should depend on automattic/blocks-engine-php-transformer directly and use Automattic\BlocksEngine\PhpTransformer\HtmlTransformer\HtmlTransformer. H2BC remains a stable compatibility shim for callers that already depend on the html_to_blocks_* PHP functions, raw-handler arrays, fallback hooks, diagnostics, or automatic WordPress write/read hooks.

Existing H2BC consumers can continue to load the shim in two modes:

• Plugin mode: activate the plugin and it automatically converts raw HTML to blocks on wp_insert_post() and REST editor reads for public REST-enabled post types.
• Package mode: composer require chubes4/html-to-blocks-converter and load WordPress. Composer autoload registers the same conversion library and automatic hooks through the version registry. Consumers can also call html_to_blocks_raw_handler() directly.

Description

This package is a compatibility facade for callers that still use the html_to_blocks_* APIs. It delegates conversion to Blocks Engine's HtmlTransformer, keeps the WordPress plugin/package shell, and adapts the canonical result into the historical raw-handler arrays, fallback hooks, diagnostics, and automatic write/read hooks.

Legacy Use Cases

• Migrating legacy content to Gutenberg blocks
• Importing content from external sources via REST API
• Programmatically creating posts with block-based content
• Converting HTML from headless CMS or content pipelines

Delegated Block Output

The plugin exposes Gutenberg block arrays returned by Blocks Engine through the historical h2bc facade. H2BC does not maintain a separate supported-block registry or local transform priority list.

For the source-of-truth status of Blocks Engine-backed output, observed fallbacks, future candidates, and context-required block families, see the Core Block Coverage Matrix.

For Site Editor and block theme boundaries, including which block families should not be inferred from raw HTML alone, see Site Editor Boundary.

For the supported subset the public h2bc facade keeps aligned with Gutenberg's rawHandler, see Gutenberg rawHandler Parity.

Unsupported top-level elements are preserved as core/html instead of guessed. When that fallback is used, h2bc fires html_to_blocks_unsupported_html_fallback with the unsupported HTML fragment, fallback context, and generated block so production pipelines can log, warn, or fail on unexpected fallback usage.

Downstream tools can call html_to_blocks_get_capabilities() for a stable capability inventory instead of parsing source. The inventory reports the package version, raw handler availability, the Blocks Engine provider, supported core blocks observed through the provider, and fallback/metrics hook names.

Installation For Existing H2BC Consumers

Install H2BC only when you need the historical html_to_blocks_* compatibility surface. New projects should install the canonical Blocks Engine PHP Transformer package directly instead of adding H2BC as an active dependency.

1. Download the plugin zip file
2. Navigate to Plugins > Add New > Upload Plugin
3. Upload the zip file and activate

Or clone directly to your plugins directory:

cd wp-content/plugins
git clone https://github.com/chubes4/html-to-blocks-converter.git

Existing shim consumers can also install it as a Composer package:

composer require chubes4/html-to-blocks-converter

Composer autoloads library.php, which registers the conversion library through an Action-Scheduler-style version registry. The winning library version loads the raw handler and the automatic write/read hooks so bundled consumers get the same HTML → blocks behavior as the standalone plugin.

When h2bc is bundled through php-scoper, callbacks registered with WordPress hook APIs must resolve inside the scoped namespace. Build hook callback strings from __NAMESPACE__ so the same source works as the standalone plugin and as a scoped dependency.

Compatibility Usage

The plugin hooks into wp_insert_post_data and automatically converts HTML content to blocks for supported post types. This behavior is retained for existing H2BC integrations; new conversion integrations should call Blocks Engine directly.

Programmatic Usage

// Content will be automatically converted to blocks
wp_insert_post([
    'post_title'   => 'My Post',
    'post_content' => '<h1>Hello World</h1><p>This is my content.</p>',
    'post_status'  => 'publish',
    'post_type'    => 'post',
]);

REST API Usage

curl -X POST https://yoursite.com/wp-json/wp/v2/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Post",
    "content": "<h1>Hello World</h1><p>This is my content.</p>",
    "status": "publish"
  }'

Direct Conversion

$html = '<h1>Title</h1><p>Paragraph with <strong>bold</strong> text.</p>';
$blocks = html_to_blocks_raw_handler(['HTML' => $html]);
$block_content = serialize_blocks($blocks);

Direct conversion requires Blocks Engine's HtmlTransformer. If the dependency cannot be autoloaded, html_to_blocks_convert() throws RuntimeException instead of falling back to a legacy internal conversion path.

Compilers and importers that need diagnostics and source references can call the result API instead:

$result = html_to_blocks_convert_fragment($html, [
    'context' => 'theme_part',
]);

$block_content = $result['block_markup'];
$diagnostics = $result['diagnostics'];
$asset_references = $result['asset_references'];
$navigation_candidates = $result['navigation_candidates'];

The result envelope includes serialized block markup, raw block arrays, normalized fallback diagnostics, conversion metrics when hooks are available, source asset references, and simple navigation candidates for downstream materializers.

REST API Read Path (v0.4.0+)

The plugin also converts HTML to blocks when the block editor loads a post via the REST API. When context=edit is requested, any post with HTML in content.raw (no `