PHPackages alleyinteractive/wp-block-converter - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. alleyinteractive/wp-block-converter ActiveLibrary[Utility & Helpers](/categories/utility) alleyinteractive/wp-block-converter =================================== Convert HTML into Gutenberg Blocks with PHP v1.8.2(5mo ago)62321.0k—7.9%5[2 PRs](https://github.com/alleyinteractive/wp-block-converter/pulls)1GPL-2.0-or-laterPHPPHP ^8.2CI passing Since Dec 20Pushed 5mo ago20 watchersCompare [ Source](https://github.com/alleyinteractive/wp-block-converter)[ Packagist](https://packagist.org/packages/alleyinteractive/wp-block-converter)[ Docs](https://github.com/alleyinteractive/wp-block-converter)[ RSS](/packages/alleyinteractive-wp-block-converter/feed)WikiDiscussions develop Synced 1mo ago READMEChangelog (10)Dependencies (8)Versions (18)Used By (1) WP Block Converter ================== [](#wp-block-converter) [![Testing Suite](https://github.com/alleyinteractive/wp-block-converter/actions/workflows/all-pr-tests.yml/badge.svg)](https://github.com/alleyinteractive/wp-block-converter/actions/workflows/all-pr-tests.yml) Convert HTML into Gutenberg Blocks with PHP Installation ------------ [](#installation) You can install the package via Composer: ``` composer require alleyinteractive/wp-block-converter ``` This project is built to be used in a WordPress environment, so it is recommended to use this package in a WordPress plugin or theme. Using it in isolation is not supported at this time. This package does not use any NPM library such as `@wordpress/blocks` to convert HTML to blocks. Usage ----- [](#usage) Use this package like so to convert HTML into Gutenberg Blocks: ``` use Alley\WP\Block_Converter\Block_Converter; $converter = new Block_Converter( 'Some HTML' ); $blocks = $converter->convert(); // Returns a string of converted blocks. ``` ### Filtering the Blocks [](#filtering-the-blocks) The blocks can be filtered on a block-by-block basis or for an entire HTML body. #### `wp_block_converter_block` [](#wp_block_converter_block) Filter the generated block for a specific node. ``` use Alley\WP\Block_Converter\Block; add_filter( 'wp_block_converter_block', function ( Block $block, \DOMElement $node ): ?Block { // Modify the block before it is serialized. $block->content = '...'; $block->blockName = '...'; $block->attributes = [ ... ]; return $block; }, 10, 2 ); ``` #### `wp_block_converter_document_html` [](#wp_block_converter_document_html) Filter the generated blocks for an entire HTML body. ``` add_filter( 'wp_block_converter_document_html', function( string $blocks, \DOMNodeList $content ): string { // ... return $blocks; }, 10, 2 ); ``` ### Attachment Parents [](#attachment-parents) When converting HTML to blocks, you may need to attach the images that were sideloaded to a post parent. After the HTML is converted to blocks, you can get the attachment IDs that were created or simply attach them to a post. ``` $converter = new Block_Converter( 'Some HTML ' ); $blocks = $converter->convert(); // Get the attachment IDs that were created. $attachment_ids = $converter->get_created_attachment_ids(); // Attach the images to a post. $parent_id = 123; $converter->assign_parent_to_attachments( $parent_id ); ``` ### Extending the Converter with Macros [](#extending-the-converter-with-macros) You can extend the converter with macros to add custom tags that are not yet supported by the converter. ``` use Alley\WP\Block_Converter\Block_Converter; use Alley\WP\Block_Converter\Block; Block_Converter::macro( 'special-tag', function ( \DOMNode $node ) { return new Block( 'core/paragraph', [], $node->textContent ); } ); // You can also use the raw HTML with a helper method from Block Converter: Block_Converter::macro( 'special-tag', function ( \DOMNode $node ) { return new Block( 'core/paragraph', [], Block_Converter::get_node_html( $node ) ); } ); ``` Macros can also completely override the default behavior of the converter. This is useful when you need to make one-off changes to the way the converter works for a specific tag. ``` use Alley\WP\Block_Converter\Block_Converter; use Alley\WP\Block_Converter\Block; Block_Converter::macro( 'p', function ( \DOMNode $node ) { if ( special_condition() ) { return new Block( 'core/paragraph', [ 'attribute' => 123 ], 'This is a paragraph' ); } return Block_Converter::p( $node ); } ); ``` WP-CLI Command -------------- [](#wp-cli-command) This package includes a WP-CLI command to bulk convert posts from HTML to Gutenberg blocks. The command uses [wp-bulk-task](https://github.com/alleyinteractive/wp-bulk-task) for efficient processing of large numbers of posts with resume support. ### Basic Usage [](#basic-usage) ``` # Convert all published posts to blocks wp block-converter # Preview changes without saving (dry run) wp block-converter --dry-run # Convert a specific post wp block-converter --post-id=123 # Convert multiple specific posts wp block-converter --post-id=123,456,789 # Convert custom post type wp block-converter --post-type=page # Convert with image sideloading wp block-converter --sideload-images # Reset the cursor to start from the beginning wp block-converter --rewind ``` ### Command Options [](#command-options) - `--post-type=` - The post type to convert. Default: `post` - `--post-status=` - The post status to filter by. Default: `publish` - `--post-id=` - Comma-separated list of post IDs to convert. If provided, only these posts will be processed. - `--dry-run` - If present, no updates will be made. Shows what would be changed. - `--rewind` - Resets the cursor so the next time the command is run it will start from the beginning. - `--sideload-images` - If present, images will be sideloaded and attached to the post. ### Features [](#features) - **Resume Support**: If the command is interrupted, it will resume from where it left off on the next run - **Progress Bar**: Shows real-time progress during bulk processing - **Dry Run Mode**: Preview changes before actually modifying posts - **Smart Skipping**: Automatically skips posts that already have blocks or have empty content - **Error Handling**: Continues processing even if individual posts fail, with detailed error reporting - **Statistics**: Displays a summary of processed, converted, skipped, and failed posts Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Credits ------- [](#credits) This project is actively maintained by [Alley Interactive](https://github.com/alleyinteractive). Like what you see? [Come work with us](https://alley.com/careers/). - [Sean Fisher](https://github.com/srtfisher) - [All Contributors](../../contributors) License ------- [](#license) The GNU General Public License (GPL) license. Please see [License File](LICENSE) for more information. ### Health Score 56 — FairBetter than 98% of packages Maintenance72 Regular maintenance activity Popularity49 Moderate usage in the ecosystem Community22 Small or concentrated contributor base Maturity67 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~77 days Recently: every ~58 days Total 15 Last Release 157d ago PHP version history (4 changes)v1.0.0PHP ^8.0 v1.1.0PHP ^8.0|^8.1|^8.2 v1.4.0PHP ^8.1|^8.2 v1.6.0PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/338d27065b1074f2d66d049d742f22996dd137eef6f91bc8f75350ceee1e8ef2?d=identicon)[srtfisher](/maintainers/srtfisher) --- Top Contributors [![srtfisher](https://avatars.githubusercontent.com/u/346399?v=4)](https://github.com/srtfisher "srtfisher (40 commits)")[![mogmarsh](https://avatars.githubusercontent.com/u/11542164?v=4)](https://github.com/mogmarsh "mogmarsh (20 commits)")[![kevinfodness](https://avatars.githubusercontent.com/u/2650828?v=4)](https://github.com/kevinfodness "kevinfodness (19 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (5 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (1 commits)") --- Tags wordpresswordpress-packagealleyinteractivewp-block-converter ### Embed Badge ![Health badge](/badges/alleyinteractive-wp-block-converter/health.svg) ``` [![Health](https://phpackages.com/badges/alleyinteractive-wp-block-converter/health.svg)](https://phpackages.com/packages/alleyinteractive-wp-block-converter) ``` ### Alternatives [civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 728272.9k20](/packages/civicrm-civicrm-core)[j0k3r/php-readability Automatic article extraction from HTML 186808.8k6](/packages/j0k3r-php-readability)[alleyinteractive/wp-curate Plugin to curate homepages and other landing pages 10154.3k](/packages/alleyinteractive-wp-curate)[spomky-labs/pwa-bundle Progressive Web App Manifest Generator Bundle for Symfony. 6144.4k1](/packages/spomky-labs-pwa-bundle)[alleyinteractive/feed-consumer Ingest external feeds and other data sources into WordPress 114.8k](/packages/alleyinteractive-feed-consumer)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)