Symfonyのコントローラで例外処理を追加する方法をやさしく解説！初心者でも安心して学べる

Symfonyのコントローラで例外処理を追加する方法

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

生徒

「Symfonyのコントローラで、エラーが出たときに止まらずに対応できる方法ってありますか？」

先生

「はい、Symfonyでは例外処理（れいがいしょり）という仕組みを使って、エラーが発生したときに適切な対応をすることができます。」

生徒

「その例外処理って難しそうですが、初心者でも使えますか？」

先生

「もちろんです！初心者でも分かるように、例え話を交えながら丁寧に説明していきましょう。」

1. 例外（エラー）とは？プログラムが止まる原因と対策をわかりやすく解説

プログラミングを学んでいると必ず出会うのが「例外（Exception）」です。これは簡単に言うと、プログラムを実行している最中に発生する「想定外のトラブル」のこと。エラーの一種ですが、適切に対処すればプログラムを安全に動かし続けることができます。

身近な例で考えてみましょう。あなたは「自動卵焼き機」というプログラムを作ったとします。

正常な動作：冷蔵庫から卵を取り出し、フライパンに入れて焼く。
例外の発生：いざ卵を取り出そうとしたら、「冷蔵庫が空っぽだった！」という状況。

この「卵がない」という予期せぬ事態が起きたとき、何も対策をしていないと機械はパニックを起こして止まってしまいます。しかし、「卵がなければ、コンビニに買いに行く」という代わりの動き（例外処理）を決めておけば、料理を完成させることができますよね。

実際のPHPプログラムで、もっともイメージしやすい「例外」のサンプルを見てみましょう。


// ユーザーが入力した数字で100を割る計算プログラム
$input_number = 0; // 例えば、ユーザーが間違えて「0」を入力したとします

// 本来、数学では数字を0で割ることはできません（ゼロ除算）
// このまま計算しようとすると「例外」が発生します
$result = 100 / $input_number;

echo "計算結果は " . $result . " です";

このコードを実行すると、次のようなエラーメッセージが表示され、プログラムはその時点で強制終了してしまいます。


Fatal error: Uncaught DivisionByZeroError: Division by zero...

このように、「データが見つからない」「インターネットがつながらない」「計算できない数字が入ってきた」といった問題が起きたときに、ユーザーに怖い英語のエラー画面を見せず、優しく「ただいま混み合っています」といった案内を出すための仕組みが、これから学ぶ「例外処理」なのです。

2. Symfonyのコントローラってなに？役割と仕組みを初心者向けに解説

Symfonyフレームワークにおいて、コントローラ（Controller）は、ユーザーからのリクエスト（URLへのアクセスなど）を一番最初に受け取り、どのような結果を返すかを判断する非常に重要な役割を担っています。

イメージしやすいように、コントローラを「レストランの料理人」に例えてみましょう。

リクエスト：お客さん（ユーザー）からの「パスタをください」という注文。
コントローラ（料理人）：注文を受けて、冷蔵庫から材料を取り出し、調理（プログラムの実行）をします。
レスポンス：出来上がった料理（画面に表示されるHTMLやデータ）をお客さんに届けます。

このように、ユーザーとシステムの橋渡しをするのがコントローラの仕事です。プログラミング未経験の方でも理解しやすいよう、簡単なプログラムの例を見てみましょう。

コントローラの基本コード例

例えば、ブラウザで「/hello」というURLにアクセスしたときに、「こんにちは！」と表示させるコントローラは以下のように書きます。


namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class HelloController
{
    #[Route('/hello')]
    public function index(): Response
    {
        // ユーザーに返すメッセージを作成
        $message = "こんにちは！Symfonyの世界へようこそ。";

        // Responseオブジェクトを使って画面に出力する
        return new Response($message);
    }
}

実行結果


こんにちは！Symfonyの世界へようこそ。

このコードでは、indexというメソッド（処理のまとまり）が、注文を受けた料理人のように動いています。最後にResponseという形で「料理（メッセージ）」を返しているのがポイントです。

実際の開発では、この処理の途中で「材料が足りない（データが見つからない）」といった予期せぬトラブルが起こることがあります。そうした事態に備えて例外処理（エラーハンドリング）を組み込むことで、画面が真っ白になったり、アプリが突然止まってしまったりするのを防ぎ、ユーザーに優しい安全なアプリケーションを作ることができるのです。

3. Symfonyでの例外処理の基本的な書き方

Symfonyのコントローラで例外処理をするには、try と catch という仕組みを使います。これは「もし何か問題があったら、それをキャッチ（つかむ）して別の処理をする」という意味です。

次のようなコードで書くことができます。


use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class SampleController
{
    #[Route('/example', name: 'example')]
    public function example(): Response
    {
        try {
            // ここにエラーが起きる可能性のある処理を書く
            $result = 10 / 0; // これはゼロで割っているのでエラーになる

            return new Response("結果: " . $result);
        } catch (\Throwable $e) {
            // 例外が起きたときの処理
            return new Response("エラーが発生しました: " . $e->getMessage());
        }
    }
}

4. このコードの動きと初心者向けの例え

このコードでは、tryブロックの中で10を0で割るという処理をしています。数学ではゼロで割ることはできないので、エラーが発生します。

しかし、このエラーは catchブロックでつかまえて、「エラーが発生しました」というメッセージを表示します。これによってプログラムが途中で止まらずにすみます。

たとえば料理で言えば、「包丁で手を切ってしまったときに、止血して続ける」ようなものです。失敗しても止まらずに続けられる仕組みがあるということです。

5. よくある例外の種類と対応方法

Symfonyのコントローラでよくある例外には、以下のようなものがあります。

DivisionByZeroError：ゼロで割ったとき
TypeError：型が合わないとき（数字じゃないものに数字の操作をしたなど）
RuntimeException：プログラムの実行時に予期せぬ問題が起きたとき

これらを個別に処理することもできますし、すべてをまとめて\ThrowableでキャッチしてもOKです。

6. Symfonyで独自のエラーメッセージを表示したいとき

catchの中で、エラーメッセージを自由に変更することができます。ユーザーにやさしい文章に変えてみましょう。


return new Response("ただいまシステムに問題が発生しています。しばらくしてからお試しください。");

これで、プログラムの中身を知らない一般のユーザーにもやさしい対応ができます。

7. 複数の例外を個別に処理する方法

例外の種類によって、対応を変えたいときは、catchを複数使うこともできます。


try {
    // エラーの起きる可能性がある処理
} catch (\DivisionByZeroError $e) {
    return new Response("ゼロでは割れません。");
} catch (\TypeError $e) {
    return new Response("型が間違っています。");
} catch (\Throwable $e) {
    return new Response("その他のエラーが発生しました。");
}

このようにすれば、エラーの内容に応じて丁寧に対応することができます。

8. まとめ：例外処理は保険のようなもの

例外処理は、いざというときの保険のようなものです。日常生活でも、何か問題が起きたときに備えて準備をしますよね。

Symfonyのコントローラでも、問題が起きる可能性のある処理にはtryとcatchを使って、プログラムが止まらないように対策しましょう。

今回紹介した方法は、初心者でも安心して取り入れられる基本の形なので、ぜひ実際に書いてみてください。

まとめ

Symfonyのコントローラにおける例外処理について、その重要性と具体的な実装方法を詳しく解説してきました。Webアプリケーション開発において、エラーは避けて通れない課題です。ユーザーが予期せぬ入力をしたり、データベースとの接続に一時的な不具合が生じたりすることは、現実の運用環境では日常茶飯事といえます。そこで重要になるのが、プログラムを「異常終了」させるのではなく、いかに「エレガントにエラーを処理し、ユーザーに適切な案内を出すか」という視点です。

堅牢なアプリケーションを作るためのポイント

PHPおよびSymfonyでの例外処理の基本は、try-catch構文を正しく使いこなすことにあります。単にエラーを握りつぶすのではなく、ログを記録したり、ユーザーにとって分かりやすいメッセージを返したりすることが、プロフェッショナルなコードへの第一歩となります。また、Symfonyフレームワーク特有の「HttpException」などを活用することで、404エラー（ページが見つからない）や403エラー（アクセス権限がない）といったHTTPステータスコードに基づいた適切なレスポンスを生成することも可能です。

実践的なエラーハンドリングの例

ここでは、より実務に近い形での例外処理の実装例を紹介します。例えば、外部のAPIからデータを取得する際や、複雑な計算を行うロジックをコントローラに記述する場合、以下のように例外の種類に応じて処理を分岐させることが推奨されます。


namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

class AdvancedExceptionController extends AbstractController
{
    #[Route('/calculate/{id}', name: 'app_calculate')]
    public function calculate(int $id): Response
    {
        try {
            // 仮のデータ取得処理。IDが100を超える場合はデータがないと想定
            if ($id > 100) {
                throw new NotFoundHttpException('指定されたデータは見つかりませんでした。');
            }

            // 何らかの複雑な計算処理
            $value = 1000 / $id;

            return new Response("計算結果は " . $value . " です。");

        } catch (NotFoundHttpException $e) {
            // データが見つからない場合の専用処理
            return new Response($e->getMessage(), 404);

        } catch (\DivisionByZeroError $e) {
            // ゼロ除算が発生した場合の処理
            return new Response("IDに0を指定することはできません。", 400);

        } catch (\Throwable $e) {
            // それ以外の予期せぬ重大なエラー
            // 実際はここで $this->logger->error($e->getMessage()); のようにログを取るのが一般的
            return new Response("システムエラーが発生しました。管理者に連絡してください。", 500);
        }
    }
}

上記のコードを実行した際、URLのパラメータとして「0」を渡すと、以下のような出力結果が得られます。


IDに0を指定することはできません。

SEOとユーザー体験（UX）の向上

例外処理を適切に行うことは、SEO対策の観点からも非常に有効です。もしプログラムが致命的なエラーで真っ白な画面（ホワイトスクリーン・オブ・デス）を表示してしまったら、検索エンジンのクローラーはサイトの品質が低いと判断してしまいます。適切なHTTPステータスコードを返し、エラーページでもサイト内のナビゲーションを維持することで、離脱率を防ぎ、検索順位の安定にも寄与します。

Symfonyを使えば、独自のエラーページ（404ページなど）をデザインすることも簡単です。開発の初期段階から「もしエラーが起きたら？」という想像力を働かせることで、ユーザーにとっても検索エンジンにとっても優しい、信頼性の高いWebサービスを構築することができるようになります。

まずは小さな処理から try-catch を取り入れてみてください。例外処理をマスターすることは、PHPエンジニアとして、そしてSymfonyエンジニアとして大きくステップアップするための必須スキルです。今回の内容を参考に、ぜひあなたのプロジェクトでも実装に挑戦してみましょう。

先生と生徒の振り返り会話

生徒

「先生、ありがとうございました！例外処理って、ただエラーを止めるだけじゃなくて、ユーザーに安心感を与えるための工夫でもあるんですね。」

先生

「その通りです。プログラムは完璧ではありません。だからこそ、エラーが起きた後の振る舞いを設計することが、プログラマーの腕の見せ所なんです。tryブロックの中に書いたコードが『理想のシナリオ』だとしたら、catchブロックは『現実的なバックアッププラン』と言えるでしょう。」

生徒

「バックアッププランですか、分かりやすいです！さっきのコードにあった \Throwable っていうのは、どんなエラーでも捕まえられる魔法の言葉みたいなものですか？」

先生

「良い質問ですね！PHP 7以降、ほとんどのエラーと例外は \Throwable インターフェースを実装しています。なので、これを指定しておけば、予期せぬエラーのほとんどをキャッチできます。ただし、何でもかんでもこれ一つで済ませるのではなく、さっきの例のように『ゼロ除算ならこれ』『データ不足ならこれ』と具体的に分けて書いたほうが、より親切なシステムになりますよ。」

生徒

「なるほど。まずは全体を \Throwable で守りつつ、よくあるミスについては個別にメッセージを用意するようにしてみます。Symfonyでの開発がもっと楽しくなりそうです！」

先生

「その意気です。エラーを恐れずに、どんどんコードを書いて失敗も経験してください。それが一番の近道ですからね。もし行き詰まったら、またいつでも聞いてください！」

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

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

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

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

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

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

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

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

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