wp-block-registration-and-assets

WordPress Block Registration and Assets

Treat block.json as the shared server/editor contract. Register from metadata, let WordPress resolve generated asset files and supports, and keep the saved markup compatible with the block's current and deprecated versions.

Choose the registration model

Need	Model
Normal editable block with custom editor UI	block.json plus JavaScript registration/build
Dynamic block with custom editor UI	metadata plus render/render_callback
Simple server-rendered fields, no custom editor JS	PHP supports.autoRegister on WordPress 7.0+
Fixed composition of existing blocks	pattern or block variation
Dynamic value in a supported existing attribute	Block Bindings source

Register on init. Prefer register_block_type_from_metadata() for one block or wp_register_block_metadata_collection() plus metadata registration for a compiled collection. Do not register the same block independently in PHP and JavaScript with drifting attributes or supports.

add_action( 'init', static function (): void {
	register_block_type_from_metadata( __DIR__ . '/build/card' );
} );

Use API version 3 for current blocks. Give every attribute a deliberate type, default, and persistence model. Attribute role: local is editor-only and is not serialized. Treat block attributes and inner markup as untrusted content.

Dynamic rendering

Use a render.php file declared by "render": "file:./render.php", or a render_callback, when output depends on current data. Keep rendering pure, cache repeated expensive reads, and return markup instead of echoing unrelated output.

$title = isset( $attributes['title'] ) ? (string) $attributes['title'] : '';
?>
<section <?php echo get_block_wrapper_attributes(); // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Core returns escaped wrapper attributes. ?>>
	<h2><?php echo esc_html( $title ); ?></h2>
</section>

Use get_block_wrapper_attributes() so style engine output, alignment, supports, and class names reach the outer element. Escape each plugin-owned value for its final HTML context. Never trust the editor's preview, block validation, or a hidden Inspector control as authorization.