ブロックテーマにPHPを部分的に組み込むハイブリッドテーマ化の手順

実現したいデザインをブロックテーマで再現するのが難しそう。
しかしブロックテーマは管理がしやすいので、クラシックテーマにはしたくない。
そこで、ブロックテーマのまま必要な一部だけにPHPを取り込む方法を模索し、解決策を見つけたので共有します。

1. PHPパーツを動かすのに必要なファイルを配置する
2. function.phpに登録
3. テンプレートでブロックを使用

1. PHPパーツを動かすのに必要なファイルを配置する

テーマフォルダの中にPHPパーツを動かすのに必要なファイルを配置します。
ファイルはどこに配置しても問題ありませんが、個人的にはWordPressの慣習に従い「parts/xxx.php」「assets/js/xxx.js」「assets/css/xxx.css」に配置することを推奨します。

今回は「parts/header.php」「assets/js/script.js」を追加しました。jsフォルダは今回新規作成したものです。CSSは短いのでルートディレクトリにあるstyle.cssに直接記述しています。

2. function.phpに登録

ブロックテーマでPHPで作成したパーツを使用するには、それを「カスタムブロック」として登録する必要があります。
以下のコードをこれからfunctions.phpに追加していきます。

このコードは3つの要素で構成されています。

2-1. ブロックの登録

// 記入例
function mytheme_register_php_header_block()
{
    register_block_type('mytheme/php-header', array(
        'render_callback' => 'mytheme_render_php_header',
    ));
}
add_action('init', 'mytheme_register_php_header_block');

function XXXX()で関数名を登録します。XXXXの部分は好きな文字列に変更可能ですが、テーマ名やプレフィックスを付けた（mytheme_やmysite_など）他の関数と被らない名前にしてください。また、変更した場合はadd_action()内の記述もあわせて変更します。
register_block_type(‘XXXX/XXXX’, array(でブロック名を登録します。XXXXの部分は好きな文字列に変更可能ですが、「名前空間/ブロック名」の記述形式を守ることと、名前空間にcoreの文字は使えないことに注意が必要です（coreはWordPress予約語であるため）。
‘render_callback’ => ‘XXXX’でコールバック関数名を登録します。XXXXの部分は好きな文字列に変更可能です。最初に決めた関数名と被らないように注意してください。
add_action(‘init’, ‘XXXX’);で実行する関数名を記述します。XXXXの部分は１で決めた関数名と同じものを入力します。

2-2. 実際の出力処理

// 記入例
function mytheme_render_php_header()
{
	ob_start();
	get_template_part('parts/php-header');
	return ob_get_clean();
}

function XXXX()で出力する関数の名前を記述します。XXXXの部分には３で決めたコールバック関数名と同じものを入力します。
get_template_part(‘XXXX’);で読み込みたいPHPファイルを指定します。XXXXの部分には、ファイルのパスを記述します（拡張子.phpは不要）。

2-3. CSSやJavaScriptの読み込み（前半）

// 記入例
function mytheme_enqueue_assets()
{
	wp_enqueue_style(
		'mytheme-style',
		get_stylesheet_uri(),
		array(),
		filemtime(get_theme_file_path('style.css'))
	);

wp_enqueue_styleを使ってPHPパーツで使用するスタイルシートを読み込みます。最初の‘XXXX’にはスタイルシートの識別名を登録しましょう（第１引数）。XXXXは好きな文字列に変更可能ですが、他のテーマやプラグインと重複しないように注意してください。
get_stylesheet_uri() . ‘XXXX’でCSSのURLを取得します（第２引数）。XXXXの部分にはCSSファイルのURLを記述してください（例：assets/css/style.css）。今回のようにルートディレクトリにあるテーマのstyle.cssを取得する場合、()以降の記述は省略可能です。
array(‘XXXX’)で、このCSSよりも先に読み込むCSSファイルを指定します（第３引数）。XXXXは任意の文字列に変更可能です（例：array(‘bootstrap’, ‘main’)）。今回はこのスタイルが依存する他のスタイルが無いため、無記入のまま進めます。
filemtime(get_theme_file_path(‘XXXX’))は、自動的にバージョン番号を変更してくれる、ブラウザキャッシュ対策に有効なコードです（第4引数）。XXXXには8で読み込んだCSSのファイル名を記述します（例：’style.css’）。

2-4. CSSやJavaScriptの読み込み（後半）

※JavaScriptを使用しない場合は、最後の「} add_action(‘wp_enqueue_scripts’, ‘mytheme_enqueue_assets’);」のみ記述して次に進んでください。

// 記入例
	wp_enqueue_script('jquery');

	wp_enqueue_script(
		'mytheme-script',
		get_template_directory_uri() . '/assets/js/script.js',
		array('jquery'),
		filemtime(get_theme_file_path('assets/js/script.js')),
		true
	);
}
add_action('wp_enqueue_scripts', 'mytheme_enqueue_assets');

今回はjQueryを使用するので、wp_enqueue_script(‘jquery’);でjQueryを読み込みます。jQueryを使用しない場合、この記述は必要ありません。
wp_enqueue_scriptを使ってPHPパーツで使用するJavaScriptを読み込みます。最初の‘XXXX’にはJavaScriptの識別名を登録しましょう（第１引数）。XXXXは好きな文字列に変更可能です。変更した場合はadd_action()内の記述もあわせて変更します。
get_template_directory_uri() . ‘XXXX’でJavaScriptのURLを取得します（第２引数）。XXXXの部分にはJavaScriptファイルのURLを記述します（例：assets/js/script.js）。
array(‘XXXX’)で、このJavaScriptよりも先に読み込むJavaScriptファイルを指定します（第３引数）。XXXXは任意の文字列に変更可能です（例：array(‘jquery’, ‘bootstrap’)）。今回はjQueryを指定しますが、jQueryを使用しない場合は無記入（array()）のまま進めます。
filemtime(get_theme_file_path(‘XXXX’))は自動的にバージョン番号を変更してくれる、ブラウザキャッシュ対策に有効なコードです（第４引数）。XXXXには１３で読み込んだJavaScriptのファイル名を記述します（例：’script.js’）。
最後の第５引数のtrueは、JavaScriptの読み込み位置の指定です。JavaScriptを</body>の直前で読み込む場合はtrue、<head>内で読み込む場合はfalseを指定します。特に理由が無ければtrueの指定を推奨します。

3. テンプレートでブロックを使用

これらの手順で、WordPressの初期化時に、登録したPHPパーツ（カスタムブロック）が使えるようになりました。早速呼び出してみましょう。
テーマのtemplatesフォルダから、PHPパーツを配置したいテンプレートファイルを開きます。
そのファイル内のPHPパーツを呼び出したい箇所に、以下のコードを記述します。

<!-- wp:XXXX/XXXX /-->

XXXX/XXXXの部分には、functions.phpで登録したブロック名を入れてください。

記述を保存し、サイト内にある該当のテンプレートを使用したページを読み込むと、PHPパーツが反映されているかと思います。（反映されていない場合、ブラウザのキャッシュを削除して再度お試しください。）

エディターから見るとこのような表示になりますが、ちゃんと機能しているので削除せずそのままにしておいてください。

とりあえず、ブロックテーマに一部だけPHPのパーツを取り込む講座はこれでおしまいです。
本当はPHPパーツにWordPressのクラスを付与することで、サイトエディターから横幅や余白のコントロールが可能になる点も書きたかったのですが、記事が長くなるうえに、調べればすぐに出てきそうな情報なので、今回は割愛します。

ここまで読んでいただきありがとうございました！
X（旧Twitter）では、WordPress開発の進捗報告なども行っておりますので、よろしければフォローやリプライなどいただけると嬉しいです。