{"id":34910529,"url":"https://github.com/arraypress/wp-block-utils","last_synced_at":"2025-12-26T11:07:35.549Z","repository":{"id":317893938,"uuid":"1013069995","full_name":"arraypress/wp-block-utils","owner":"arraypress","description":"A lean WordPress library for working with blocks and Gutenberg content.","archived":false,"fork":false,"pushed_at":"2025-10-03T17:04:15.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T19:09:01.231Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arraypress.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-03T10:05:34.000Z","updated_at":"2025-10-03T17:04:20.000Z","dependencies_parsed_at":"2025-10-06T10:17:04.688Z","dependency_job_id":null,"html_url":"https://github.com/arraypress/wp-block-utils","commit_stats":null,"previous_names":["arraypress/wp-block-utils"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/arraypress/wp-block-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-block-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-block-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-block-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-block-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arraypress","download_url":"https://codeload.github.com/arraypress/wp-block-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arraypress%2Fwp-block-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28053398,"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","status":"online","status_checked_at":"2025-12-26T02:00:06.189Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-12-26T11:07:32.187Z","updated_at":"2025-12-26T11:07:35.541Z","avatar_url":"https://github.com/arraypress.png","language":"PHP","readme":"# WordPress Block Utils - Lean Block Management\n\nA lightweight WordPress library for working with blocks and Gutenberg content. Provides clean APIs for block operations, content parsing, and analysis perfect for plugins and themes.\n\n## Features\n\n* 🎯 **Clean API**: WordPress-style snake_case methods with consistent interfaces\n* 🔍 **Built-in Search**: Block search with recursive inner block support\n* 📋 **Form-Ready Options**: Perfect value/label arrays for block type selects\n* ⚡ **Parse \u0026 Render**: Easy content parsing and block rendering\n* 🔧 **Attribute Management**: Simple block attribute manipulation\n* 📊 **Usage Analytics**: Block usage statistics and analysis\n* 🎨 **Pattern Matching**: Wildcard support for block type matching\n* 🧱 **Inner Blocks**: Full support for nested block operations\n\n## Requirements\n\n* PHP 7.4 or later\n* WordPress 5.0 or later (with Gutenberg)\n\n## Installation\n\n```bash\ncomposer require arraypress/wp-block-utils\n```\n\n## Basic Usage\n\n### Working with Single Blocks\n\n```php\nuse ArrayPress\\BlockUtils\\Block;\n\n// Get block information\n$block_name = Block::get_name( $block );\n$attributes = Block::get_attributes( $block );\n$inner_html = Block::get_inner_html( $block );\n\n// Get specific attribute\n$className = Block::get_attribute( $block, 'className', '' );\n\n// Manipulate attributes\n$block = Block::set_attribute( $block, 'className', 'my-custom-class' );\n$block = Block::remove_attribute( $block, 'unwanted-attr' );\n\n// Work with inner blocks\n$inner_blocks = Block::get_inner_blocks( $block );\n$block        = Block::add_inner_block( $block, $new_inner_block );\n\n// Check block properties\nif ( Block::has_inner_blocks( $block ) ) {\n\t// Block has inner blocks\n}\n\nif ( Block::is_reusable( $block ) ) {\n\t// Block is a reusable block\n}\n\n// Block type operations\nif ( Block::type_exists( 'custom/my-block' ) ) {\n\t$is_dynamic = Block::is_dynamic( 'custom/my-block' );\n\t$category   = Block::get_category( 'custom/my-block' );\n}\n\n// Pattern matching\nif ( Block::matches( $block, 'core/*' ) ) {\n\t// Block is a core block\n}\n\nif ( Block::matches( $block, 'core/heading' ) ) {\n\t// Block is specifically a heading block\n}\n\n// Convert blocks\n$block_string  = Block::to_string( $block );\n$block_array   = Block::to_array( $block_string );\n$rendered_html = Block::render( $block );\n\n// Utility functions\n$short_name = Block::strip_core_namespace( 'core/paragraph' ); // Returns: 'paragraph'\n```\n\n### Working with Multiple Blocks\n\n```php\nuse ArrayPress\\BlockUtils\\Blocks;\n\n// Parse content\n$blocks      = Blocks::parse( $post_content );\n$post_blocks = Blocks::get_from_post( 123 );\n\n// Render blocks\n$html       = Blocks::render( $blocks );\n$serialized = Blocks::serialize( $blocks );\n\n// Search and filter\n$headings      = Blocks::get_by_type( $blocks, 'core/heading' );\n$core_blocks   = Blocks::get_by_type( $blocks, 'core/*' );\n$custom_blocks = Blocks::search_by_type( $blocks, 'custom/*' );\n\n// Search by attributes\n$large_headings = Blocks::get_by_attribute( $blocks, 'level', 1 );\n\n// Get from current content\n$images    = Blocks::get_from_content( 'core/image' );\n$galleries = Blocks::get_from_content( 'core/gallery', $custom_content );\n\n// Block type registry\n$all_types    = Blocks::get_registered_types();\n$type_options = Blocks::get_type_options(); // For form selects\n$custom_only  = Blocks::get_type_options( false ); // Exclude core blocks\n\n// Search block types\n$matching_types = Blocks::search_types( 'heading' );\n\n// Statistics and analysis\n$total_blocks  = Blocks::count_total();\n$heading_count = Blocks::count_by_type( 'core/heading' );\n$usage_stats   = Blocks::get_usage_stats();\n$most_used     = Blocks::get_most_used_type();\n\n// Conditional checks\nif ( Blocks::uses_block_type( 'core/gallery' ) ) {\n\t// Content uses gallery blocks\n}\n\nif ( Blocks::is_editor_available() ) {\n\t// Gutenberg functions are available\n}\n\n// Content manipulation\n$modified_content = Blocks::replace_by_type( $content, 'core/heading', function ( $block ) {\n\treturn Block::set_attribute( $block, 'className', 'custom-heading' );\n} );\n\n$clean_content = Blocks::remove_by_type( $content, 'core/separator' );\n```\n\n### Advanced Examples\n\n```php\n// Find all headings and analyze their levels\n$content  = get_the_content();\n$headings = Blocks::get_from_content( 'core/heading', $content );\n\n$heading_levels = array_map( function ( $heading ) {\n\treturn Block::get_attribute( $heading, 'level', 2 );\n}, $headings );\n\n$level_distribution = array_count_values( $heading_levels );\n\n// Replace all paragraphs with custom styling\n$new_content = Blocks::replace_by_type( $content, 'core/paragraph', function ( $block ) {\n\t$existing_class = Block::get_attribute( $block, 'className', '' );\n\t$new_class      = trim( $existing_class . ' custom-paragraph' );\n\n\treturn Block::set_attribute( $block, 'className', $new_class );\n} );\n\n// Get usage statistics for reporting\n$stats = Blocks::get_usage_stats();\necho \"Block Usage Report:\\n\";\nforeach ( $stats as $block_type =\u003e $count ) {\n\t$clean_name = Block::strip_core_namespace( $block_type );\n\techo \"- {$clean_name}: {$count} blocks\\n\";\n}\n\n// Find blocks with specific attributes\n$blocks_with_ids = Blocks::filter( $blocks, function ( $block ) {\n\treturn ! empty( Block::get_attribute( $block, 'anchor' ) );\n} );\n\n// Check if content is block-based\nif ( Blocks::count_total() \u003e 0 ) {\n\techo \"This content uses the block editor\";\n} else {\n\techo \"This might be classic editor content\";\n}\n```\n\n### Block Type Options for Forms\n\n```php\n// Get all block types for admin select\n$block_options = Blocks::get_type_options();\n// Returns: [['value' =\u003e 'core/paragraph', 'label' =\u003e 'Paragraph'], ...]\n\n// Get only custom blocks\n$custom_options = Blocks::get_type_options( false );\n\n// Use in WordPress settings\nadd_settings_field(\n\t'allowed_blocks',\n\t'Allowed Block Types',\n\tfunction () {\n\t\t$options = Blocks::get_type_options();\n\t\t// Render select with options\n\t},\n\t'my_settings_page'\n);\n```\n\n## Key Features\n\n- **Pattern Matching**: Use `core/*` to match all core blocks\n- **Recursive Search**: Find blocks deep within inner blocks\n- **Attribute Management**: Easy get/set/remove operations\n- **Usage Analytics**: Understand block usage patterns\n- **Form Integration**: Ready-made options for admin interfaces\n- **Content Manipulation**: Replace and remove blocks programmatically\n- **Type Safety**: Proper null handling and type checking\n\n## Requirements\n\n- PHP 7.4+\n- WordPress 5.0+ (with Gutenberg support)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the GPL-2.0-or-later License.\n\n## Support\n\n- [Documentation](https://github.com/arraypress/wp-block-utils)\n- [Issue Tracker](https://github.com/arraypress/wp-block-utils/issues)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fwp-block-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farraypress%2Fwp-block-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farraypress%2Fwp-block-utils/lists"}