{"id":19107782,"url":"https://github.com/alleyinteractive/wp-block-converter","last_synced_at":"2025-04-05T04:08:42.922Z","repository":{"id":64967658,"uuid":"580044189","full_name":"alleyinteractive/wp-block-converter","owner":"alleyinteractive","description":"Convert HTML into Gutenberg Blocks with PHP","archived":false,"fork":false,"pushed_at":"2025-02-18T19:04:51.000Z","size":296,"stargazers_count":48,"open_issues_count":6,"forks_count":4,"subscribers_count":25,"default_branch":"develop","last_synced_at":"2025-03-29T03:05:45.218Z","etag":null,"topics":["wordpress","wordpress-package"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alleyinteractive.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-19T15:24:14.000Z","updated_at":"2025-03-26T10:06:28.000Z","dependencies_parsed_at":"2023-01-08T18:02:21.295Z","dependency_job_id":"33c9f0bb-6dab-48a2-b1bd-52de42283162","html_url":"https://github.com/alleyinteractive/wp-block-converter","commit_stats":{"total_commits":61,"total_committers":6,"mean_commits":"10.166666666666666","dds":0.5737704918032787,"last_synced_commit":"9679a9ca46f91d3942497c7a514b22617de5b2dc"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":"alleyinteractive/create-php-package","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-block-converter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-block-converter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-block-converter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alleyinteractive%2Fwp-block-converter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alleyinteractive","download_url":"https://codeload.github.com/alleyinteractive/wp-block-converter/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284944,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["wordpress","wordpress-package"],"created_at":"2024-11-09T04:13:58.331Z","updated_at":"2025-04-05T04:08:42.884Z","avatar_url":"https://github.com/alleyinteractive.png","language":"PHP","readme":"# WP Block Converter\n\n[![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)\n\nConvert HTML into Gutenberg Blocks with PHP\n\n## Installation\n\nYou can install the package via Composer:\n\n```bash\ncomposer require alleyinteractive/wp-block-converter\n```\n\nThis project is built to be used in a WordPress environment, so it is recommended to use this\npackage in a WordPress plugin or theme. Using it in isolation is not supported at this time. This\npackage does not use any NPM library such as `@wordpress/blocks` to convert HTML to blocks.\n\n## Usage\n\nUse this package like so to convert HTML into Gutenberg Blocks:\n\n```php\nuse Alley\\WP\\Block_Converter\\Block_Converter;\n\n$converter = new Block_Converter( '\u003cp\u003eSome HTML\u003c/p\u003e' );\n\n$blocks = $converter-\u003econvert(); // Returns a string of converted blocks.\n```\n\n### Filtering the Blocks\n\nThe blocks can be filtered on a block-by-block basis or for an entire HTML body.\n\n#### `wp_block_converter_block`\n\nFilter the generated block for a specific node.\n\n```php\nuse Alley\\WP\\Block_Converter\\Block;\n\nadd_filter( 'wp_block_converter_block', function ( Block $block, \\DOMElement $node ): ?Block {\n\t// Modify the block before it is serialized.\n\t$block-\u003econtent = '...';\n\t$block-\u003eblockName = '...';\n\t$block-\u003eattributes = [ ... ];\n\n\treturn $block;\n}, 10, 2 );\n```\n\n#### `wp_block_converter_document_html`\n\nFilter the generated blocks for an entire HTML body.\n\n```php\nadd_filter( 'wp_block_converter_document_html', function( string $blocks, \\DOMNodeList $content ): string {\n\t// ...\n\treturn $blocks;\n}, 10, 2 );\n```\n\n### Attachment Parents\n\nWhen converting HTML to blocks, you may need to attach the images that were\nsideloaded to a post parent. After the HTML is converted to blocks, you can get\nthe attachment IDs that were created or simply attach them to a post.\n\n```php\n$converter = new Block_Converter( '\u003cp\u003eSome HTML \u003cimg src=\"https://example.org/\" /\u003e\u003c/p\u003e' );\n$blocks = $converter-\u003econvert();\n\n// Get the attachment IDs that were created.\n$attachment_ids = $converter-\u003eget_created_attachment_ids();\n\n// Attach the images to a post.\n$parent_id = 123;\n$converter-\u003eassign_parent_to_attachments( $parent_id );\n```\n\n### Extending the Converter with Macros\n\nYou can extend the converter with macros to add custom tags that are not yet\nsupported by the converter.\n\n```php\nuse Alley\\WP\\Block_Converter\\Block_Converter;\nuse Alley\\WP\\Block_Converter\\Block;\n\nBlock_Converter::macro( 'special-tag', function ( \\DOMNode $node ) {\n\treturn new Block( 'core/paragraph', [], $node-\u003etextContent );\n} );\n\n// You can also use the raw HTML with a helper method from Block Converter:\nBlock_Converter::macro( 'special-tag', function ( \\DOMNode $node ) {\n\treturn new Block( 'core/paragraph', [], Block_Converter::get_node_html( $node ) );\n} );\n```\n\nMacros can also completely override the default behavior of the converter. This\nis useful when you need to make one-off changes to the way the converter works\nfor a specific tag.\n\n```php\nuse Alley\\WP\\Block_Converter\\Block_Converter;\nuse Alley\\WP\\Block_Converter\\Block;\n\nBlock_Converter::macro( 'p', function ( \\DOMNode $node ) {\n\tif ( special_condition() ) {\n\t\treturn new Block( 'core/paragraph', [ 'attribute' =\u003e 123 ], 'This is a paragraph' );\n\t}\n\n\treturn Block_Converter::p( $node );\n} );\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Credits\n\nThis project is actively maintained by [Alley Interactive](https://github.com/alleyinteractive). Like what you see? [Come work with us](https://alley.com/careers/).\n\n- [Sean Fisher](https://github.com/srtfisher)\n- [All Contributors](../../contributors)\n\n## License\n\nThe GNU General Public License (GPL) license. Please see [License File](LICENSE) for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-block-converter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falleyinteractive%2Fwp-block-converter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleyinteractive%2Fwp-block-converter/lists"}