WordPress ルーティングデバッグ完全ガイド｜テンプレート選択とクエリ解析を可視化

WordPress のテーマ開発では、以下のようなシーンに遭遇することがよくあります。

  • どのタイミングでどのテンプレートが選ばれているのか確認したい
  • URL のリライトルールが正しく機能しているかを調べたい
  • 意図しない 404 エラーが発生する原因を突き止めたい

この記事では、テーマ開発時に役立つ 「ルーティングの流れを可視化するデバッグ用プラグイン」 の作成方法を詳しく解説します。
テンプレート選択やクエリ解析をログで追跡できるので、デバッグ効率が格段に向上します。

1. プラグインの概要

このプラグインは、WordPress のルーティング処理に関わる以下のフックにフックして、リクエストやテンプレート情報をログ出力します。

フック出力内容
muplugins_loadedプラグイン読み込み直後の URI
init初期化処理の完了時点の URI
parse_requestクエリ解析時の URI と query_vars
pre_handle_404404 判定直前の URI とステータス
template_include選択されたテンプレートファイルのパス
template_redirectテンプレート表示直前の URI

これにより、処理の流れを時系列で把握できます。

2. プラグインコード

以下のコードを deep-route-debug.php という名前で保存し、
/wp-content/plugins/ ディレクトリに配置して有効化します。

<?php
/**
 * Plugin Name: Deep Route Debug（仮）
 * Description: ルーティングの実際の到達点を debug.log に出力
 */

// WP_DEBUG_LOG が OFF でも error_log は出力されますが、
// 以下を wp-config.php に追加しておくと管理がしやすくなります。
// define('WP_DEBUG', true);
// define('WP_DEBUG_LOG', true);

// mu-plugins 読み込み直後
add_action('muplugins_loaded', function () {
    error_log('[DeepRoute] muplugins_loaded: ' . ($_SERVER['REQUEST_URI'] ?? ''));
});

// init フック
add_action('init', function () {
    error_log('[DeepRoute] init: ' . ($_SERVER['REQUEST_URI'] ?? ''));
});

// クエリ解析
add_action('parse_request', function ($wp) {
    error_log('[DeepRoute] parse_request: ' . ($_SERVER['REQUEST_URI'] ?? ''));
    error_log('[DeepRoute] query_vars: ' . json_encode($wp->query_vars, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE));
});

// 404 判定直前
add_filter('pre_handle_404', function ($preempt, $wp_query) {
    error_log('[DeepRoute] pre_handle_404: is_404? ' . ($wp_query->is_404 ? 'true' : 'false') . ' URI=' . ($_SERVER['REQUEST_URI'] ?? ''));
    return $preempt;
}, 10, 2);

// 選択されたテンプレート
add_filter('template_include', function ($template) {
    error_log('[DeepRoute] template_include: ' . $template . ' URI=' . ($_SERVER['REQUEST_URI'] ?? ''));
    return $template;
}, 1000);

// template_redirect 直前
add_action('template_redirect', function () {
    error_log('[DeepRoute] template_redirect: ' . ($_SERVER['REQUEST_URI'] ?? ''));
});

3. プラグインの使い方

ステップ1：有効化

WordPress 管理画面の「プラグイン一覧」から Deep Route Debug（仮） を有効化します。

ステップ2：ログを確認

ルーティング処理が走るたびに、wp-content/debug.log または PHP のエラーログに情報が記録されます。

出力例：

[28-Aug-2025 05:14:27 UTC] [DeepRoute] muplugins_loaded: /sample-page/
[28-Aug-2025 05:14:27 UTC] [DeepRoute] init: /sample-page/
[28-Aug-2025 05:14:27 UTC] [DeepRoute] parse_request: /sample-page/
[28-Aug-2025 05:14:27 UTC] [DeepRoute] query_vars: {"pagename":"sample-page"}
[28-Aug-2025 05:14:27 UTC] [DeepRoute] pre_handle_404: is_404? false URI=/sample-page/
[28-Aug-2025 05:14:27 UTC] [DeepRoute] template_redirect: /sample-page/
[28-Aug-2025 05:14:27 UTC] [DeepRoute] template_include: /wp-content/themes/my-theme/page.php URI=/sample-page/

ステップ3：問題箇所を特定

  • 404 エラーの原因調査
    pre_handle_404 のログで判定タイミングを確認できます。
  • テンプレートの選択確認
    template_include で実際に選ばれたテンプレートファイルを追跡できます。
  • クエリ変数の解析
    parse_request の query_vars を見れば、URL パラメータが正しく解析されているか一目瞭然です。

4. 活用シーン

  • カスタムリライトルールの検証
    オリジナルルールを設定したあと、処理の流れを確認。
  • 仮想ページ（バーチャルページ）開発
    template_include で、想定どおりのテンプレートが読み込まれているか確認可能。
  • カスタム投稿タイプの挙動確認
    query_vars を追跡することで、正しいクエリパラメータが渡されているか調べられます。

5. 注意点

  • 本番環境では無効化
    ログ出力が増えるため、開発・ステージング環境での利用を推奨します。
  • ログの肥大化に注意
    アクセス数の多い環境では、ログが急激に大きくなる可能性があります。必要に応じてローテーション設定を行いましょう。
  • カスタマイズも可能
    error_log() をファイル出力に切り替えれば、専用ログとして管理することも可能です。

まとめ

この Deep Route Debug（仮） プラグインを使えば、テーマ開発中の ルーティング・テンプレート選択・クエリ解析 が一目で分かります。

  • 処理フックの到達点を追跡
  • クエリ変数やテンプレートを可視化
  • バグの原因をスピーディーに把握

特に、カスタム投稿タイプ や 複雑なリライトルール、仮想ページ を扱うプロジェクトでは、デバッグ効率を大幅に向上させることができます。

スポンサーリンク

コメント

タイトルとURLをコピーしました