PHPackages                             cloakwp/block-parser - 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. [Parsing & Serialization](/categories/parsing)
4. /
5. cloakwp/block-parser

ActiveLibrary[Parsing & Serialization](/categories/parsing)

cloakwp/block-parser
====================

Parse Gutenberg + ACF Blocks into structured objects.

0.0.16(2mo ago)2871LGPL-3.0-onlyPHPPHP >=7.4

Since Sep 10Pushed 2mo agoCompare

[ Source](https://github.com/cloak-labs/wp-block-parser)[ Packagist](https://packagist.org/packages/cloakwp/block-parser)[ RSS](/packages/cloakwp-block-parser/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (8)Versions (17)Used By (1)

CloakWP Block Parser
====================

[](#cloakwp-block-parser)

CloakWP Block Parser is a PHP library designed to parse and transform Gutenberg and ACF blocks into structured objects/JSON. This package is part of the CloakWP ecosystem, but can be used independently or as a dependency of your own plugins/themes/packages.

Features
--------

[](#features)

- Parse Gutenberg (core) blocks into objects/JSON
- Parse Advanced Custom Fields (ACF) blocks into objects/JSON
- Extensible architecture for custom block transformers
- Filters for modifying parsed block data

Motivation
----------

[](#motivation)

WordPress block content is stored as HTML strings in the database rather than as structured data (e.g. JSON). This is particularly a problem for decoupled/headless projects where you may wish to render things your own way; to do so, you need the blocks in JSON/structured object form -- turns out this is surprisingly difficult to achieve. CloakWP Block Parser simplifies this process by providing a clean and organized way to parse and transform blocks content into structured data.

Installation
------------

[](#installation)

You can install this package via Composer:

```
composer require cloakwp/block-parser
```

Example Output
--------------

[](#example-output)

 Structured data```
[
  {
    "name": "core/paragraph",
    "type": "core",
    "attrs": {
      "content": "Contact us via phone (123) 456-7890 or email info@example.com.",
      "dropCap": false
    }
  },
  {
    "name": "acf/hero",
    "type": "acf",
    "attrs": {
      "style": {
        "spacing": {
          "margin": {
            "bottom": "var:preset|spacing|60"
          }
        }
      },
      "className": "pb-8 md:pb-10",
      "align": "full",
      "backgroundColor": "bg-root-dim"
    },
    // ACF field data:
    "data": {
      "hero_style": "image_right",
      "image": {
        "medium": {
          "src": "http://localhost/app/uploads/sites/8/2024/08/example-300x200.jpeg",
          "width": 300,
          "height": 200
        },
        "large": {
          "src": "http://localhost/app/uploads/sites/8/2024/08/example-1024x683.jpeg",
          "width": 1024,
          "height": 683
        },
        "full": {
          "src": "http://localhost/app/uploads/sites/8/2024/08/example.jpeg",
          "width": 1620,
          "height": 1080
        },
        "alt": "example alt description",
        "caption": "example caption"
      },
      "eyebrow": "WordPress Experts",
      "h1": "Build your dream website.",
      "subtitle": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "cta_buttons": false,
      "show_social_proof": false
    }
  }
]
```

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

```
use CloakWP\BlockParser\BlockParser;

$postId = 123;
$blockParser = new BlockParser();
$blockData = $blockParser->parseBlocksFromPost($postId);
```

### Extending

[](#extending)

 Custom TransformersThe BlockParser uses the built-in core function, `parse_blocks()`, to initially parse the blocks, but unfortunately this function doesn't do the full job. So, we extend the basic built-in parsing with block "transformers".

By default, the BlockParser uses the following transformers:

- CoreBlockTransformer (for Gutenberg core blocks)
- ACFBlockTransformer (for ACF blocks)

You can extend the BlockParser by registering your own custom block transformers for certain block types, or to override the default transformers:

```
// when you define your Transformer class, you must implement the BlockTransformerInterface and define
// a static $type property, which indicates the block type that the transformer should be applied to:
class MyCustomACFBlockTransformer implements BlockTransformerInterface
{
  protected static string $type = 'acf'; // this will override the default ACFBlockTransformer

  public function transform(WP_Block $block, int|null $postId = null): array
  {
    // your custom data transformation code here -- whatever you return here will be the final block data
  }
}

// now register the transformer with your BlockParser instance:
$blockParser = new BlockParser();
$blockParser->registerBlockTransformer(MyCustomACFBlockTransformer::class);
```

If in the above example you want to add a transformer for some custom block type, you just specify a custom value for the static `$type` property, and then extend the `BlockParser` class and override the `determineBlockType()` method to add your logic for determining when a block is of your custom type; for example:

```
class MyCustomBlockParser extends BlockParser
{
  protected function determineBlockType(WP_Block $block): string
  {
    if ($block->blockName === 'my-custom-block-name') {
      return 'custom';
    }

    return parent::determineBlockType($block);
  }
}

class MyCustomBlockTransformer implements BlockTransformerInterface
{
  protected static string $type = 'custom';

  public function transform(WP_Block $block, int|null $postId = null): array
  {
    // ..
  }
}

$postId = 123;
$blockParser = new MyCustomBlockParser();
$blockParser->registerBlockTransformer(MyCustomBlockTransformer::class)

// now any blocks with name 'my-custom-block-name' will be transformed by MyCustomBlockTransformer's transform() method
$blockData = $blockParser->parseBlocksFromPost($postId);
```

 Filter HooksBesides creating custom transformers, you can also modify parsed block data using filters. These filters are applied after the block has been transformed by the appropriate transformer, but before the block is returned:

```
add_filter('cloakwp/block', function(array $parsedBlock, WP_Block $wpBlock) {
  // modify $parsedBlock here
  return $parsedBlock;
}, 10, 2);
```

The `cloakwp/block` filter accepts two modifiers, `name` and `type`, for more granular targeting:

```
add_filter('cloakwp/block/name=core/paragraph', function(array $parsedBlock, WP_Block $wpBlock) {
  // modify $parsedBlock here
  return $parsedBlock;
}, 10, 2);

add_filter('cloakwp/block/type=acf', function(array $parsedBlock, WP_Block $wpBlock) {
  // modify $parsedBlock here
  return $parsedBlock;
}, 10, 2);
```

You can also filter ACF field values within ACF blocks using the `cloakwp/block/field` filter:

```
add_filter('cloakwp/block/field', function(mixed $fieldValue, array $fieldObject) {
  // modify $fieldValue here
  return $fieldValue;
}, 10, 2);
```

The `cloakwp/block/field` filter accepts three modifiers, `name` (i.e. ACF field name), `type` (i.e. ACF field type), and `blockName` (i.e. ACF block name), for more granular targeting:

```
add_filter('cloakwp/block/field/name=my_acf_field', function(mixed $fieldValue, array $fieldObject) {
  // modify $fieldValue here
  return $fieldValue;
}, 10, 2);

add_filter('cloakwp/block/field/type=image', function(mixed $fieldValue, array $fieldObject) {
  // modify $fieldValue here
  return $fieldValue;
}, 10, 2);

add_filter('cloakwp/block/field/blockName=acf/hero-section', function(mixed $fieldValue, array $fieldObject) {
  // modify $fieldValue here
  return $fieldValue;
}, 10, 2);
```

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance88

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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 ~36 days

Recently: every ~48 days

Total

16

Last Release

61d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6029133664b39b787817bddb9c1840cfdb8fac3b0ee8dee66edc10a6b9391f80?d=identicon)[kaelan](/maintainers/kaelan)

---

Top Contributors

[![kaelansmith](https://avatars.githubusercontent.com/u/60372141?v=4)](https://github.com/kaelansmith "kaelansmith (41 commits)")

### Embed Badge

![Health badge](/badges/cloakwp-block-parser/health.svg)

```
[![Health](https://phpackages.com/badges/cloakwp-block-parser/health.svg)](https://phpackages.com/packages/cloakwp-block-parser)
```

###  Alternatives

[andreyryabin/sprint.editor

Редактор для контент-менеджеров

485.6k](/packages/andreyryabin-sprinteditor)[freshsystems/wp-acf-markdown-field

Adds a Markdown field to Advanced Custom Fields.

159.2k](/packages/freshsystems-wp-acf-markdown-field)[gccloud/parser

CodeIgniter 3 Parser library extension

166.5k](/packages/gccloud-parser)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)