Symfonyのエラーページ（404・500）をカスタマイズする方法を完全解説！初心者でもわかる例外処理とデバッグ

Symfonyでエラーページ（404, 500など）をカスタマイズする方法

先生と生徒の会話形式で理解しよう

生徒

「Symfonyでページが見つからないときに、英語のエラー画面が出てきて困っています…」

先生

「Symfonyでは、404や500といったエラーページを自分用に作り替えることができます。」

生徒

「プログラミング未経験でもできますか？」

先生

「大丈夫です。仕組みを一つずつ見ていけば、誰でも理解できます。」

1. Symfonyのエラーページとは？

Symfonyのエラーページとは、エラーが発生したときに表示される特別な画面のことです。例えば、存在しないURLにアクセスした場合は「404エラー」、プログラム内部で問題が起きた場合は「500エラー」が表示されます。初期状態のSymfonyでは、開発者向けの英語メッセージが表示されるため、一般ユーザーには少し難しく感じられます。そのため、エラーページをカスタマイズして、日本語で分かりやすい画面にすることが重要です。

2. 404エラーと500エラーの違いを知ろう

404エラーは「ページが見つかりません」という意味で、存在しない住所に手紙を出した状態に例えられます。一方、500エラーは「サーバー内部で問題が起きました」という意味で、家の中で機械が壊れて動かなくなった状態です。 Symfonyでは、このようなエラーを例外処理として扱い、状況に応じた画面を表示できます。例外とは「想定外の出来事」のことだと覚えておくと理解しやすいです。

3. エラーページを置く場所（Twigテンプレート）

Symfonyでエラーページをカスタマイズする場合、templates/bundles/TwigBundle/Exception というフォルダを使います。ここにHTMLに近い形式のTwigテンプレートを作成します。 Twigとは、Symfonyで使われる画面表示用の仕組みで、「画面の設計図」のような役割を持っています。


templates/
└─ bundles/
   └─ TwigBundle/
      └─ Exception/
         ├─ error404.html.twig
         └─ error500.html.twig

4. 404エラーページをカスタマイズする方法

404エラー専用のページは、error404.html.twigという名前で作成します。中身は普通のHTMLとほぼ同じなので、初心者でも安心です。ユーザーに対して「ページが見つからない理由」や「トップページへの案内」を書くと親切です。


<h1>ページが見つかりません</h1>
<p>お探しのページは削除されたか、URLが間違っている可能性があります。</p>
<a href="/">トップページへ戻る</a>

5. 500エラーページをカスタマイズする方法

500エラーはシステム側の問題なので、専門的な内容を表示する必要はありません。「現在利用できません」といったやさしい表現にするのがポイントです。 Symfonyでは、error500.html.twigを用意するだけで自動的に切り替わります。


<h1>システムエラーが発生しました</h1>
<p>ご迷惑をおかけして申し訳ありません。しばらくしてから再度お試しください。</p>

6. 開発環境と本番環境で表示が変わる理由

Symfonyには「開発環境」と「本番環境」があります。開発環境では、バグを見つけやすくするために詳細なエラー情報が表示されます。一方、本番環境では、ユーザー向けにシンプルなエラーページが表示されます。この切り替えによって、セキュリティと使いやすさを両立しています。


APP_ENV=prod
APP_DEBUG=0

7. コントローラで例外を投げる基本例

Symfonyでは、プログラムの途中で意図的にエラーを発生させることもできます。これを「例外を投げる」と呼びます。例えば、データが見つからない場合に404エラーを表示したいときに使います。


use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

throw new NotFoundHttpException('データが見つかりません');

8. エラーページをカスタマイズするメリット

Symfonyでエラーページをカスタマイズすると、ユーザーが混乱しにくくなります。また、サイト全体のデザインを統一できるため、信頼感の向上にもつながります。 SEOの面でも、突然英語の画面が出るより、日本語で案内されたほうが離脱を防げます。 404エラーや500エラーを丁寧に扱うことは、使いやすいWebアプリケーションを作る第一歩です。

公的機関での指導実績【Symfony大規模設計実践セミナー】

エンタープライズSymfony実践講座：大規模DX基盤を支える疎結合設計とドメイン駆動開発

#商用設計 #APIアーキテクチャ #市場価値最大化

ハローワーク職業訓練講師の実績を持つプロが監修。商用PHP開発の「現場の作法」を完全伝授。

「大規模システムの秩序」を設計する。SymfonyでエンタープライズLOD（設計の質）を極める。

本講座では、単なるWeb機能の構築ではなく、「再利用性とテスト容易性を追求した疎結合設計」という高度な技術を学びます。世界標準の堅牢性を誇るSymfonyを通じて、大規模開発やマイクロサービス化で必須となるDI（依存性の注入）やイベント駆動設計を最短距離で身につけます。

具体的なワークショップ内容と環境

【つくるもの】
エンタープライズ環境の標準となる「疎結合なバックエンド基盤」を構築します。Service Containerの高度な設定、Doctrine ORMによる複雑なデータマッピング、Bundle構造の理解など、「数年先もメンテナンス可能な商用コード」をゼロから体験してください。

【開発環境】
高度なリファクタリングを可能にするPHPStormの機能をフル活用。Docker環境での開発はもちろん、静的解析ツール（PHPStan）やCI/CDを意識した自動テスト環境まで、大規模プロジェクトの標準フローを再現します。