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.

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.

• 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

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.

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.

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.

// 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',
]);

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"
  }'

$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.

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 <!-- wp: block markup) is automatically converted to proper block markup before the editor sees it.

This means the block editor always shows proper blocks — even when post_content was written as raw HTML by a migration script, an external API, or another plugin. No "Convert to blocks" prompt.

The REST filters are registered at init priority 20 to ensure all custom post types are available.

When loaded by Composer inside WordPress, the version registry loads both the conversion API and the automatic hooks. Consumers that only need direct conversion can call the raw handler without going through the hooks:

// Available after Composer autoload runs.
$blocks = html_to_blocks_raw_handler([
    'HTML' => '<h1>Hello</h1><p>World</p>',
]);

Package consumers can call the raw handler directly for adapter pipelines, while h2bc still registers its normal hooks for plain HTML write/read paths.

Modify which post types support automatic HTML-to-blocks conversion.

add_filter('html_to_blocks_supported_post_types', function($post_types) {
    $post_types[] = 'custom_post_type';
    return $post_types;
});

Default: all public REST-enabled post types via get_post_types(['show_in_rest' => true, 'public' => true])

Observe unsupported or intentionally ambiguous fragments that are preserved as core/html instead of guessed.

add_action('html_to_blocks_unsupported_html_fallback', function($html, $context, $block) {
    error_log('h2bc fallback: ' . ($context['reason'] ?? 'unknown'));
}, 10, 3);

Runs after the version registry initializes the winning h2bc copy. Receives the loaded version string.

The public H2BC facade delegates HTML-to-block conversion to Blocks Engine's PHP transformer. H2BC keeps the WordPress plugin/package shell, HTML normalization, shortcode splitting, fallback event adaptation, result envelope, and automatic write/read hooks around that canonical transformer.

library.php is the package entry point. It registers the local copy's version and initializer with HTML_To_Blocks_Versions. On plugins_loaded:1, the registry initializes the highest registered version exactly once. This lets multiple plugins bundle the package while the standalone plugin is also active; everyone gets the newest loaded conversion library and no duplicate class/function definitions.

html-to-blocks-converter.php is the plugin shell. It performs the standalone plugin's WordPress/PHP guard checks, then loads library.php. Composer consumers skip the plugin shell but still load the raw handler and automatic hooks through the library initializer.

• WordPress 6.4+ (required for WP_HTML_Processor)
• PHP 8.1+

GPL v2 or later

Directly inspired by the Gutenberg project's client-side raw handling implementation.

Chris Huber