CakePHP 4 でエラーページをカスタムする方法 / Twin Turbo Computing

はじめに

今日は CakePHP 4 でエラーページをカスタマイズする方法をご紹介します。

確認に使用したのは CakePHP 4.1.6 (cakephp/app 4.1.2) です。

目次

デフォルトのレイアウトファイルは /templates/layout/error.php です。
これを変更することで、エラー画面のレイアウトを独自のものにできます。

エラーページのテンプレートは errors/error400.php と error500.php にあるのですが、
レイアウトはこれらの下記で指定されています。

errors/error400.php

$this->layout = 'error';

ここを変更することで別のレイアウトファイルを作ったり、既存のテンプレを使用することも可能です。

前述の通り、エラーページのテンプレートは下記２つです。

400 と 500 は HTTP ステータスコードを表していて、
400 は無効な URL や対象レコードが見つからないような場合、500 はサーバ側のエラー時に使用されるテンプレートです。

エラー画面のテンプレートにはいろいろと書かれていますが、
HTML 部分は最下部にあります。

/templates/errors/error400.php

...
$this->end();
endif;
?>
<!-- ↓ ここから下を変更 -->
<h2>閲覧できません</h2>
<p>ページが削除されたか、一時的にアクセスできない状況の可能性があります。</p>

どちらのテンプレートでも上部に IF 文や関数がたくさんあって、一見分かりづらいかもしれませんね。
このプログラム部分には debug 時の挙動書かれています。

HTML 部分だけを分離したい場合や、400 と 500 ともに同じエラーメッセージを表示するような場合は element() を使うと良いかもしれません。

/templates/element/errors/content.php

<h2>閲覧できません</h2>
<p>ページが削除されたか、一時的にアクセスできない状況の可能性があります。</p>

/templates/errors/error400.php

...
$this->end();
endif;
?>
<!-- ↓ 変更 -->
<?php $this->element('errors/content') ?>

Custom Error Templates (Error & Exception Handling - CakePHP 4.x Strawberry Cookbook): https://book.cakephp.org/4/en/development/errors.html#custom-error-templates
HTTP レスポンスステータスコード - HTTP: https://developer.mozilla.org/ja/docs/Web/HTTP/Status

debug を true にした際のレイアウトは下記にあります。

/vendor/cakephp/cakephp/templates/layout/dev_error.php

/templates/layout/dev_error.php という名前で独自のレイアウトファイルを置くことで、デバッグ画面のカスタムも可能です。

エラー画面は大切なページの１つで、その後の行動をナビゲートするものや、心理的負担を軽減するデザインなどにするのが良いと考えています。

なるべく予算をかけずにどう実現するかも重要になることが多く、クリエイターの腕の見せ所でもありますね。

ところでエラー時にはログの取得と解析も大切です。CakePHP 4 にはログの便利な機能もありますので、まだという方は是非使ってみてください。

CakePHP 4.0 で 404 Not Found エラーを別ログに保存する方法 / Twin Turbo Computing: https://tt-computing.com/cake4_0-log-404
CakePHP 4 のエラーログをレベルに応じて異なるファイルに出力する / Twin Turbo Computing: https://tt-computing.com/cake4-log-file-name