[
  {
    "name": "core/paragraph",
    "type": "core",
    "attrs": {
      "content": "Contact us via phone <a href=\"tel:123-456-7890\">(123) 456-7890</a> or email <a href=\"mailto:info@example.com\">info@example.com</a>.",
      "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
    }
  }
]

The 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);

Besides 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);