Download the PHP package automattic/block-delimiter without Composer

Block Delimiter

Efficiently work with block structure

How to install block-delimiter

To use this package in your WordPress plugin, you can require both this package and the Jetpack Autoloader in your project's composer.json file.

Overview

The Block Delimiter package provides an efficient, streaming parser for working with WordPress block structure without the memory overhead of parse_blocks(). It's designed for scenarios where you need to inspect, find, or modify specific blocks without parsing the entire block tree.

The package includes two classes:

• Block_Scanner (recommended): A high-performance, mutable scanner that provides the best CPU performance while maintaining near-zero memory overhead.
• Block_Delimiter (legacy): A generator-based approach that returns new instances for each delimiter, suitable for existing code that relies on the scan_delimiters() interface.

Block_Scanner (Recommended)

The Block_Scanner class is modeled after the WordPress HTML API and provides the best performance characteristics. It mutates itself during scanning and requires a new instance for each document scan.

Basic Block Scanning

Find and iterate through all block delimiters in a document:

Output:

Finding Specific Block Types

Efficiently find blocks of a specific type without parsing everything:

Output:

Extracting Block Attributes

Parse JSON attributes only when needed:

Output:

Counting Block Types

Get a count of all block types in a document:

Output:

Error Handling

Check for parsing errors:

Output:

Block_Delimiter (Legacy)

The Block_Delimiter class provides a generator-based interface that returns new instances for each delimiter. While it offers the same memory efficiency, it has higher CPU overhead compared to Block_Scanner.

Basic Block Scanning

Find and iterate through all block delimiters in a document:

Output:

Finding Specific Block Types

Efficiently find blocks of a specific type without parsing everything:

Output:

Extracting Block Attributes

Parse JSON attributes only when needed:

Output:

Counting Block Types

Get a count of all block types in a document:

Output:

Extracting Complete Block Content

Extract an entire block including its delimiters and content:

Output:

Modifying Block Content

Transform block content efficiently without parsing the entire tree:

Output:

Error Handling

Check for parsing errors:

Output:

Performance Benefits

Both classes offer significant performance advantages over parse_blocks():

• Zero memory overhead: No block tree construction
• Streaming processing: Process only what you need
• Lazy parsing: JSON attributes parsed only when accessed
• String-based operations: Work directly with the source text
• Early termination: Stop processing when you find what you need

Contribute

You can contribute to this package by submitting a pull request to the Jetpack repository.

Coding standards

This package follows standards set by the Jetpack Code Sniffer package, with a few exceptions documented in the package's .phpcs.dir.xml file.

Testing

When introducing new features or making changes to existing code, please add tests.

To run the tests, you can use the following command:

Using this package in your WordPress plugin

If you plan on using this package in your WordPress plugin, we would recommend that you use Jetpack Autoloader as your autoloader. This will allow for maximum interoperability with other plugins that use this package as well.

Security

Need to report a security vulnerability? Go to https://automattic.com/security/ or directly to our security bug bounty site https://hackerone.com/automattic.

License

Block Delimiter is licensed under GNU General Public License v2 (or later)