BLOG ブログ

はじめに

CakePHPのDebugKitは、CakePHP開発・デバッグ用の便利なツールバープラグインです。
開発時に適宜有効化することでSQLクエリのログ、セッション、リクエスト情報、タイマー、環境変数などをブラウザ上ですばやく確認することができます。

先日弊社のクライアント様のCakePHPアプリケーションを、CakePHP 4.3から5系へ移行するプロジェクトが発生しました。
公式のマイグレーションも確立されておりほぼほぼスムーズに作業ができたのですが何事にも例外はあるものです。

移行後、DebugKitのツールバーを表示するといつものケーキのアイコンが表示されず、ログを確認すると MissingRouteException が発生しているようでした。

原因は、ログインURLの生成時に plugin を指定していなかったことです。
'plugin' => null を追加して解消しました。

同じような構成を検討されている方の参考になれば幸いです。

背景・目的

今回の移行対象は、prefixで管理画面と一般画面を分けたアプリケーションです。
ログイン認証には、Authenticationプラグインを使っています。

開発環境はDockerで動かしており、デバッグ用にDebugKitを入れています。
目的は、CakePHP 4.3から5.0への移行を、動作を変えずに終えることでした。

気づいた経緯（症状）

移行後、DebugKitのツールバーを表示するタイミングで、ログインページのルートが見つからないというエラーが出ました。

症状として、ログには次の MissingRouteException が記録されていました。
実際のログを単純化したものです。

A route matching "array (
  'prefix' => '（prefix名）',
  'controller' => 'Logins',
  'action' => 'index',
  'plugin' => 'DebugKit',
)" could not be found.

注目したのは、配列に 'plugin' => 'DebugKit' が入っている点です。
弊社のコードでは plugin を指定していません。

発生元は、getAuthenticationService() 内の Router::url() でした。
場所は src/Application.php です。

先に試したこと：READMEの ignoreAuthorization では直らなかった

公式READMEにある対処法を試しましたが、症状は変わりませんでした。

DebugKitのREADMEには、ツールバーが出ないときの代表的な原因が載っています。
その1つに、Authorizationプラグインを使う場合の設定があります。

設定とは、DebugKit.ignoreAuthorization を true にすることです。
ツールバーが出ない原因に当てはまると考え、この設定を試しました。

設定の書き方の例です。

Configure::write('DebugKit.ignoreAuthorization', true);

※この設定は、開発環境でだけ使ってください。
本番環境には入れないでください。

しかし、設定を入れても症状は変わりませんでした。

READMEの項目は、Authorizationプラグイン（認可）を使う場合のものです。
今回の例外は、Authenticationプラグイン（認証）のログインURL生成で起きていました。

対象が違うため、設定の効果がなかったと考えています。

教訓：公式の対処法で直らないときは、例外の発生元を読み直します。
対処法が対象とする箇所と、自分の症状の発生箇所が合っているかを確認します。

原因1：DebugKitのリクエストから plugin が補われていた

原因は、Router::url() が、指定しなかった plugin を現在のリクエストから補ったことです。

Router::url() とは、配列で指定した情報からURLを作るCakePHPのメソッドです。
指定しなかったキーは、現在のリクエストの値で補われると判断しました。

ツールバーの表示では、DebugKit自身のコントローラーが動きます。
このとき、現在のリクエストの plugin は DebugKit です。

認証ミドルウェアは、リクエストのたびに getAuthenticationService() を呼びます。
そのため、DebugKitのリクエストでも、ログインURLの生成が走ります。

その結果、DebugKitの Logins コントローラーを探すことになり、ルートが見つからずに例外になりました。

教訓：認証やミドルウェアは、あらゆるリクエストで動きます。
こうした処理でURLを作るときは、現在のリクエストに頼らず、plugin と prefix を明示します。

原因2：CakePHP 4.3で出なかった理由は特定できていない

同じコードはCakePHP 4.3では問題を起こさず、5.0への移行後に初めてエラーになりました。
ただし、その理由は検証できていません。

同じ症状は、CakePHP 4.xでも報告されています。
たとえば、CakePHP公式フォーラムの投稿があります。
4.xでAuthenticationプラグインを入れた後、ツールバーが出なくなったという内容です。

解決策は、Router::url() に plugin と prefix の指定を足すことでした。
原因の構造は、5系に限った話ではないようです。

このため、5系の仕様変更が原因だと断定はできません。
移行でDebugKitなどのバージョンが変わったことが影響した可能性はありますが、推測の域を出ません。

教訓：バージョンアップ後に初めて出た不具合でも、新バージョンの仕様変更とは限りません。
旧バージョンでは条件が揃わず、潜んでいただけの可能性も切り分けに入れます。

解決策：URL生成に plugin を明示する

解決策は、URLを生成する配列に 'plugin' => null を足すだけです。

次のコードは、実際のコードを単純化・一般化したものです。
言語はPHPで、対象はCakePHP 5.0の src/Application.php です。

修正前のコードです（NG例）。

$loginUrl = Router::url([
    'controller' => 'Logins',
    'action' => 'index',
]);

修正後のコードです。

$loginUrl = Router::url([
    'plugin' => null,
    'controller' => 'Logins',
    'action' => 'index',
]);

弊社では、リクエストから読み出したprefixで、管理画面用と一般画面用のログインURLを分けています。
このように分岐している場合は、どちらのURL生成にも同じ指定が必要です。

確認方法と、直らない場合

ツールバーが正常に表示され、ログに例外が出なければ解消です。
弊社では、修正後にツールバーが正常に表示されることを確認しました。

1. 開発環境で debug を true にして、画面を開く
2. DebugKitのツールバーが表示されることを確認する
3. ログに MissingRouteException が記録されていないことを確認する

直らない場合は、Application.php 内にある、ほかの Router::url() も確認してください。
unauthenticatedRedirect など、認証設定の中に同じ形のURL生成があれば、同じ指定が必要です。

まとめ

• Router::url() は、指定しなかった plugin や prefix を、現在のリクエストから補う
• 認証やミドルウェアなど、全リクエストで動く処理では、plugin と prefix を明示する
• 移行後に初めて出た不具合は、仕様変更と決めつけず、旧バージョンで潜んでいた可能性も切り分ける
• 公式READMEの対処法で直らないときは、例外の発生元を読み直し、対処法の対象と症状が合っているかを確認する

関連記事

• Debugkit not showing due to missing route – Plugins – Cake Software Foundation, Inc.
• debug_kit/README.md at 5.x · cakephp/debug_kit

おわりに

ここまで読んでいただき、ありがとうございました。
私たちは、できることを誠実にやる会社です。

Web・システム・AIのことで気になることがあれば、
「何から相談すればいいか分からない」段階でも大丈夫です。
お気軽にご相談ください。

▶ お問い合わせ

本記事は、Claudeでのやり取りをもとに作成し、加筆・修正しております。