Define Blocks Gutenberg blocks in pure PHP

Many custom blocks are small forms: a quote, a name, an image and a couple of settings. With the official tooling each of them becomes a JavaScript project with a block.json, an edit component and a build.

Define Blocks keeps the definition in PHP. The editor interface comes precompiled inside the plugin, so your project has nothing to build. Block definitions are plain PHP arrays and go through version control and code review with the rest of the theme.

Every schema entry has a scope. The five scopes match the places where core blocks keep their controls. A scope can be repeated, and each inspector entry becomes a separate panel.

All fields write to the same values object, so a toggle in the toolbar can control a condition in the sidebar. Without scopes, an associative array of fields goes to the canvas.

Each type has its own editor control, a predictable value shape and a sanitizer. There are also 58 aliases, so image works as media and toggle as checkbox. Type names are case-insensitive, and you can register your own types.

Google maps and geocoders need an API key through defb_google_maps_key, Mapbox a token through defb_mapbox_key. OpenStreetMap needs neither. In the toolbar scope, select, checkbox, text, number and autocomplete switch to their toolbar versions automatically.

A field with show appears when its condition is true; hide does the opposite. Simple checks can be written as an array, the rest as a string expression. The same rules run in the editor (JavaScript) and on save (PHP), and hidden fields are not validated.

A malformed expression leaves the field visible and, with WP_DEBUG on, reports the error. in and contains compare plain values, not the {value, label} items of multi-select, chips or taxonomy fields.

What the callback receives

$attributes['values'] is a flat array: groups and tabs don't add nesting. Fields without a default may be missing, so read them with ??. Rich text is HTML: print it with wp_kses_post().

Preview in the editor

With 'frontend_preview' => true the block toolbar shows a Preview button. The render runs through a REST request, which checks edit_post, and its HTML replaces the fields. The previous result stays visible while the next one loads. The shorthand also opens new blocks in preview mode; to have only the button, use 'settings' => [ 'frontendPreview' => true ].

Preview styles are not loaded automatically. Pass file paths or raw CSS to the defb_preview_style filter: the rules are scoped to .defb-preview and relative url()s are rebased.

define_block_type( 'acme/quote', [
    'title'    => 'Quote',
    'settings' => [ 'frontendPreview' => true ],
    'schema'   => [ 'text' => [ 'type' => 'richtext', 'label' => 'Text' ] ],
    'render'   => __DIR__ . '/blocks/quote.php',
] );
 
add_filter( 'defb_preview_style', function ( $sources ) {
    $sources[] = get_theme_file_path( 'assets/css/blocks.css' );
    $sources[] = '.quote { border-left: 3px solid currentColor; padding-left: 1rem; }';
    return $sources;
} );

Values are stored in post_content, in the block's values attribute. defb_get_block() returns the first instance of a block, or a single field of it. defb_get_blocks() returns every instance, including those inside InnerBlocks, with defaults applied.

$post_id = get_queried_object_id();
 
$hero    = defb_get_block( $post_id, 'acme/hero' );
$heading = defb_get_block( $post_id, 'acme/hero', 'heading' );
$image   = $hero['image']['url'] ?? '';
 
foreach ( defb_get_blocks( $post_id, 'acme/slide' ) as $slide ) {
    printf( '<li>%s</li>', esc_html( $slide['title'] ?? '' ) );
}

When another tool is a better fit

1. Download the master branch zip from GitHub. There is no tagged release yet.
2. Extract it into wp-content/plugins and rename define-blocks-master to define-blocks.
3. Activate the plugin and call define_block_type() on init. Registrations are collected at priority 99; later calls are ignored and reported when WP_DEBUG is on.

cd wp-content/plugins
curl -L -o define-blocks.zip https://github.com/corsivo-suite/define-blocks/archive/refs/heads/master.zip
unzip define-blocks.zip
mv define-blocks-master define-blocks
rm define-blocks.zip
wp plugin activate define-blocks

git clone https://github.com/corsivo-suite/define-blocks.git wp-content/plugins/define-blocks
wp plugin activate define-blocks

add_action( 'init', function () {
    if ( ! function_exists( 'define_block_type' ) ) {
        return;
    }
    define_block_type( 'acme/hello', [
        'title'  => 'Hello',
        'schema' => [ 'name' => [ 'type' => 'text', 'label' => 'Name', 'default' => 'world' ] ],
        'render' => function ( array $attributes ): string {
            return '<p>Hello, ' . esc_html( $attributes['values']['name'] ?? 'world' ) . '.</p>';
        },
    ] );
} );

The plugin is not on wordpress.org or Packagist. To update it, replace the folder or run git pull. Wrapping your calls in function_exists() keeps the site working if the plugin is deactivated. The wp commands require WP-CLI; the Plugins screen works as well.