WordPressで独自デザインの案内ボックスやCTAボタン、定型パーツを記事内に配置したいとき、これまでは「functions.phpでショートコードを作成する」か「Node.jsとReact（JSX）のビルド環境を構築してカスタムブロックを開発する」のどちらかを選ぶ必要がありました。しかし近年のWordPressコアおよびGutenbergの進化により、JavaScriptを1行も書かずにPHPだけでカスタムブロックを登録できる「PHPブロック登録（supports.autoRegister）」と、出力HTMLを正規表現なしで安全に書き換える「HTML API（WP_HTML_Tag_Processor）」が実用段階に入っています。

この2つの標準機能を組み合わせると、npmビルド環境を用意することなくブロックエディタ対応の独自ブロックを作成でき、さらに既存ブロックのHTML属性やCSSクラスも壊さずにカスタマイズできます。本記事では、両機能の仕組みと最小構成の実装コード、そして実務での使い分けを図解とともに整理します。

従来のブロック開発が抱えていた課題とPHPブロック登録の登場

ブロックエディタ（Gutenberg）が標準となって以降も、制作現場では長らくショートコードが使われ続けてきました。その大きな理由は、カスタムブロックを1つ作るだけでもNode.jsやnpm、Webpack（@wordpress/scripts）といったフロントエンドのビルド環境が必要になり、ちょっとした文言や属性の修正でもJavaScriptの再ビルドが発生していたためです。

一方で、ショートコードには「ブロックエディタ上で実際の見た目を確認できない」「属性の入力ミスや角括弧の消し忘れが起きる」といった運用上の弱点があります。このギャップを埋めるために導入されたのが、PHP側のブロック定義（register_block_type）からエディタ用の設定UIとプレビューを自動生成するsupports.autoRegisterの仕組みです。

PHPブロック登録（autoRegister）の仕組みと実装コード

PHPブロック登録では、register_block_type()の引数にあるsupports配列へ‘autoRegister’ => trueを指定し、ブロックが受け取る属性（attributes）と描画用のコールバック関数（render_callback）を定義します。

属性の型からサイドバー入力欄を自動生成

WordPressは定義されたattributesのデータ型（string、boolean、number、enumなど）を読み取り、ブロックを選択した際の右サイドバー（インスペクター）に対応する入力フィールドを自動的に配置します。値が変更されるとサーバーサイド描画（ServerSideRender）によってエディタ上の表示も即座に更新されます。

PHPだけで完結するカスタムブロックの記述例

たとえば、見出し・本文・注意喚起アイコンの有無をサイドバーから切り替えられる「お知らせボックス」ブロックは、テーマのfunctions.phpや専用プラグイン内に以下のPHPコードを記述するだけで登録できます。

add_action( 'init', function () {
    register_block_type( 'my-theme/notice-box', array(
        'title'       => 'お知らせボックス',
        'category'    => 'text',
        'icon'        => 'info-outline',
        'supports'    => array(
            'autoRegister' => true,
            'color'        => array(
                'background' => true,
                'text'       => true,
            ),
            'spacing'      => array(
                'padding' => true,
                'margin'  => true,
            ),
        ),
        'attributes'  => array(
            'heading' => array(
                'type'    => 'string',
                'default' => 'ご確認いただきたいポイント',
            ),
            'message' => array(
                'type'    => 'string',
                'default' => 'ここに案内テキストを入力します。',
            ),
            'isImportant' => array(
                'type'    => 'boolean',
                'default' => false,
            ),
        ),
        'render_callback' => function ( $attributes, $content, $block ) {
            $heading      = esc_html( $attributes['heading'] ?? '' );
            $message      = esc_html( $attributes['message'] ?? '' );
            $is_important = ! empty( $attributes['isImportant'] );
            $modifier     = $is_important ? ' is-important' : '';

            $wrapper_attributes = get_block_wrapper_attributes( array(
                'class' => 'my-notice-box' . $modifier,
            ) );

            return sprintf(
                '<div %1$s><p class="my-notice-box__title">%2$s</p><p class="my-notice-box__body">%3$s</p></div>',
                $wrapper_attributes,
                $heading,
                $message
            );
        },
    ) );
} );

get_block_wrapper_attributes()を併用することで、supportsで有効化した背景色・文字色・余白（padding/margin）といったWordPress標準のスタイル設定も自動的にラッパー要素のクラスやインラインスタイルへ反映されます。

HTML API（WP_HTML_Tag_Processor）による安全なHTML操作

PHPでブロックを出力したり、既存のコアブロック（段落・画像・見出し・ボタンなど）の出力HTMLをrender_blockフィルターでカスタマイズしたりする際、これまではstr_replace()やpreg_replace()（正規表現）で文字列を直接置換する手法が使われてきました。しかし正規表現によるHTML置換は、属性の順序が変わったりテキスト内に同じ文字列が含まれていたりするとHTML構造を壊してしまうリスクがあります。

WP_HTML_Tag_Processorの4つの主要メソッド

WordPressコアに標準搭載されているWP_HTML_Tag_Processorは、HTML5仕様に準拠した高速なトークン解析器です。DOMDocumentのように閉じタグが省略されたHTML断片で文字化けや勝手なタグ補完を起こすことなく、狙ったタグの属性やクラスだけを安全に書き換えられます。

• next_tag( $query )：指定したタグ名やクラス名に一致する次のHTML要素へカーソルを進める
• add_class( $class_name ) / remove_class( $class_name )：既存のclass属性を解析し、重複を防ぎながらCSSクラスを着脱する
• set_attribute( $name, $value ) / remove_attribute( $name )：エスケープ処理を自動で行いながらdata-*属性やaria-*属性を付与・削除する
• get_updated_html()：変更を反映した最終的なHTML文字列を取得する

render_blockフィルターと組み合わせた実装例

たとえば、記事内の画像ブロック（core/image）に含まれるimgタグへ独自のクラスと属性を安全に追加したい場合は、以下のように記述できます。

add_filter( 'render_block_core/image', function ( $block_content, $block ) {
    $processor = new WP_HTML_Tag_Processor( $block_content );

    if ( $processor->next_tag( array( 'tag_name' => 'img' ) ) ) {
        $processor->add_class( 'custom-zoom-image' );

        if ( null === $processor->get_attribute( 'decoding' ) ) {
            $processor->set_attribute( 'decoding', 'async' );
        }
    }

    return $processor->get_updated_html();
}, 10, 2 );

このように記述すれば、すでにclass属性が存在するかどうかや、シングルクォート・ダブルクォートの違いを意識することなく、確実に目的のimgタグだけを更新できます。

実務での使い分けと組み合わせパターン

PHPブロック登録（autoRegister）とHTML API（WP_HTML_Tag_Processor）は、それぞれの得意領域を押さえて組み合わせることで、サイト制作と保守の効率を大きく高められます。

• 定型ボックスやCTAの脱ショートコード化：これまでショートコードで実装していた「資料請求バナー」「監修者プロフィール枠」「関連記事カード」などをautoRegisterでブロック化すると、執筆者がエディタ上でプレビューを見ながら安全に入力できるようになります。
• 既存コアブロックへの属性付与：外部リンクへの属性追加や、特定クラスを持つグループブロックへの計測用data属性の付与には、render_blockフックとWP_HTML_Tag_Processorの組み合わせが適しています。
• Interactivity APIとの連携：WP_HTML_Tag_Processorを使ってdata-wp-interactiveやdata-wp-on–click属性をPHP側で付与すれば、既存のブロック出力を壊さずに動的なUI機能を後からアドオン形式で組み込むことも可能です。

まとめ：ビルド不要のブロック登録とHTML APIで保守性の高い開発へ

WordPressの「PHPブロック登録（supports.autoRegister）」と「HTML API（WP_HTML_Tag_Processor）」は、複雑なJavaScriptビルド環境や危うい正規表現に頼らず、PHPの標準コードだけでモダンなブロックエディタ対応を実現する心強い機能です。

まずは小さく管理しやすい定型パーツや既存のrender_blockフィルターから取り入れて、編集者にとっても開発者にとっても扱いやすいWordPress環境を整えてみてください。