【PHP8.x】Exception::previousプロパティの使い方

Copy
1<?php
2
3/**
4 * Custom exception for application-specific errors during question paper processing.
5 * This class inherits from RuntimeException and allows for clearer error identification
6 * in an application that processes "previous year question papers".
7 */
8class QuestionPaperProcessingException extends RuntimeException
9{
10    // No additional methods are needed for this example,
11    // as it primarily leverages the exception chaining mechanism provided by PHP's Throwable interface.
12}
13
14/**
15 * Simulates loading data for a "previous year question paper".
16 * In a real application, this might involve reading from a database, file system, or API.
17 * This function is designed to sometimes fail, demonstrating a low-level error.
18 *
19 * @param string $paperId The identifier for the question paper (e.g., '2023_math').
20 * @return array An array containing simulated paper data if successful.
21 * @throws RuntimeException If there's a simulated issue preventing data loading.
22 */
23function loadQuestionPaperData(string $paperId): array
24{
25    // Simulate a failure condition for a specific paper ID.
26    // For example, the file might be missing, permissions are incorrect, or data is corrupted.
27    if ($paperId === '2023_math_paper') {
28        // Throw a generic RuntimeException to represent a low-level problem.
29        throw new RuntimeException("Failed to read data for '{$paperId}'. The paper file might be missing or unreadable.");
30    }
31
32    // Simulate successful data loading for other papers.
33    return [
34        'id' => $paperId,
35        'title' => "Previous Year {$paperId} Question Paper",
36        'total_questions' => 25,
37        'published_date' => '2023-01-15'
38    ];
39}
40
41/**
42 * Attempts to process a "previous year question paper".
43 * This function demonstrates how to catch a low-level exception and then re-throw
44 * a more specific application-level exception, while preserving the original
45 * exception as the 'previous' exception for debugging purposes. This is known as
46 * exception chaining.
47 *
48 * @param string $paperId The identifier of the question paper to process.
49 * @throws QuestionPaperProcessingException If processing fails due to any underlying reason.
50 */
51function processPreviousYearQuestionPaper(string $paperId): void
52{
53    echo "Attempting to process previous year question paper: '{$paperId}'\n";
54    try {
55        $paperData = loadQuestionPaperData($paperId);
56        echo "  Successfully loaded: {$paperData['title']}.\n";
57        // In a real scenario, more processing logic would follow here.
58        echo "  Processing complete for '{$paperId}'.\n";
59    } catch (RuntimeException $e) {
60        // Catch the low-level RuntimeException thrown by loadQuestionPaperData().
61        // We re-throw our custom QuestionPaperProcessingException.
62        // The original exception ($e) is passed as the third argument to the
63        // new exception's constructor. This argument is stored internally
64        // as the 'previous' exception.
65        throw new QuestionPaperProcessingException(
66            "An application error occurred while preparing '{$paperId}'. " . $e->getMessage(),
67            0, // Optional: exception code (0 for default)
68            $e  // This is the 'previous' exception, preserving the original cause.
69        );
70    }
71}
72
73// --- Main execution block to demonstrate exception chaining ---
74
75echo "--- Scenario 1: Successful Processing ---\n";
76try {
77    // This call is expected to succeed.
78    processPreviousYearQuestionPaper('2022_physics_paper');
79} catch (QuestionPaperProcessingException $e) {
80    // This block should not be reached in this scenario.
81    echo "  Error: Caught an unexpected exception during successful processing: " . $e->getMessage() . "\n";
82}
83echo "\n";
84
85echo "--- Scenario 2: Failed Processing with Chained Exception ---\n";
86try {
87    // This call is expected to fail and trigger exception chaining.
88    processPreviousYearQuestionPaper('2023_math_paper');
89} catch (QuestionPaperProcessingException $e) {
90    // We catch our custom application-specific exception here.
91    echo "  Error: Caught application-specific exception for '2023_math_paper': " . $e->getMessage() . "\n";
92
93    // Access the 'previous' exception using the getPrevious() method.
94    // The 'previous' property (internal) holds the Throwable object that was
95    // passed as the third argument to the current exception's constructor.
96    // getPrevious() returns `?Throwable`, meaning it can be null if no previous
97    // exception was set.
98    $previousException = $e->getPrevious();
99
100    if ($previousException !== null) {
101        echo "    Detailed Cause (from the previous exception):\n";
102        echo "      Type: " . get_class($previousException) . "\n"; // e.g., RuntimeException
103        echo "      Message: " . $previousException->getMessage() . "\n";
104        echo "      File: " . $previousException->getFile() . "\n";
105        echo "      Line: " . $previousException->getLine() . "\n";
106    } else {
107        echo "    No previous exception was chained to this error.\n";
108    }
109}
110
111?>

このPHPコードは、エラーが発生した際にその原因を連鎖させて追跡しやすくする「例外チェーン」という重要な仕組みを示しています。

具体的には、loadQuestionPaperData関数が過去問のデータ読み込みをシミュレートし、特定の条件下でRuntimeExceptionを発生させます。これをprocessPreviousYearQuestionPaper関数がキャッチし、よりアプリケーション固有のQuestionPaperProcessingExceptionとして再スローします。この際、元のRuntimeExceptionが新しいQuestionPaperProcessingExceptionのコンストラクタの第三引数として渡されます。

このようにして渡された元の例外は、新しい例外の内部的なpreviousプロパティに保存されます。このpreviousプロパティには直接アクセスできませんが、getPrevious()メソッドを通して取得することが可能です。getPrevious()メソッドは引数を取りません。戻り値は?Throwable型で、前の例外が設定されていればそのThrowableオブジェクトを返し、設定されていなければnullを返します。

この仕組みにより、システムが複雑な場合でも、最終的に発生したエラーだけでなく、そのエラーを引き起こした根本的な原因（低レベルなエラー）まで遡って確認できるようになります。これは、エラーの原因究明やデバッグ作業を効率的に進める上で非常に役立つため、システムエンジニアにとって必須の知識です。

Copy
1<?php
2
3/**
4 * PHPのExceptionクラスの`previous`プロパティ（例外チェーン）の利用方法を実演するサンプルコード。
5 *
6 * `previous`プロパティは、ある例外を捕捉し、それを原因として新しい上位の例外を
7 * 発生させる（スローする）際に、元の例外情報を保持するために使用されます。
8 * これにより、エラーが発生した際の原因究明が容易になります。
9 *
10 * システムエンジニアを目指す初心者の方へ:
11 * 複雑なアプリケーションでは、様々な層（データベース、ファイルシステム、ネットワークなど）で
12 * エラーが発生する可能性があります。例外チェーンを使用することで、低レベルで発生した
13 * 具体的なエラー（例: データベース接続失敗）を、ユーザーに表示される高レベルなエラー
14 * （例: レポート生成失敗）と関連付け、問題の根本原因を追跡しやすくなります。
15 *
16 * PHP 8では、`Exception`クラスのコンストラクタの第3引数で前の`Throwable`オブジェクトを渡すことができ、
17 * その前の`Throwable`オブジェクトは、`Exception::previous`プロパティ（または`getPrevious()`メソッド）で取得できます。
18 */
19
20/**
21 * 例外チェーンの動作をデモンストレーションする関数。
22 *
23 * この関数内で、意図的に例外を発生させ、それを捕捉して別の例外でラップし、
24 * 最終的にトップレベルで捕捉して`previous`プロパティの内容を表示します。
25 */
26function demonstrateExceptionChaining(): void
27{
28    // 低レベルの操作をシミュレートする無名関数
29    // 例: データベース操作、ファイルI/O、外部API呼び出しなど
30    $lowLevelOperation = function (): void {
31        // 実際には、ここで何か失敗する可能性のある処理を実行する
32        // 例として、ファイル書き込み失敗のRuntimeExceptionをスローする
33        throw new RuntimeException("データファイルへの書き込みに失敗しました。", 100);
34    };
35
36    try {
37        // ビジネスロジック層の操作をシミュレートする無名関数
38        // この層は低レベル操作に依存しており、そのエラーを捕捉して変換する
39        $businessLogicOperation = function (callable $dependency): void {
40            try {
41                $dependency(); // 低レベル操作を呼び出す
42            } catch (RuntimeException $e) {
43                // 低レベルのRuntimeExceptionを捕捉し、よりビジネスロジックに近い例外でラップする。
44                // ここで、元の例外($e)を新しい例外の第3引数（previous）として渡す。
45                throw new Exception("レポート生成プロセス中にエラーが発生しました。", 200, $e);
46            }
47        };
48
49        // ビジネスロジック操作を実行する
50        $businessLogicOperation($lowLevelOperation);
51
52    } catch (Throwable $e) { // 最上位で例外を捕捉 (ExceptionとErrorの両方に対応)
53        echo "--- 最上位で捕捉された例外情報 ---\n";
54        echo "メッセージ: " . $e->getMessage() . "\n";
55        echo "コード: " . $e->getCode() . "\n";
56        echo "例外タイプ: " . get_class($e) . "\n";
57        echo "発生ファイル: " . $e->getFile() . " (行: " . $e->getLine() . ")\n";
58
59        // `previous`プロパティ（または`getPrevious()`メソッド）を使って、元の例外にアクセスする
60        // PHP 7.4以降では、`$e->previous`として直接プロパティにアクセス可能。
61        // それ以前のバージョンや、より汎用的な場合は`$e->getPrevious()`メソッドを使用する。
62        $previousException = $e->previous;
63
64        if ($previousException !== null) {
65            echo "\n--- この例外の原因となった元の例外情報 (previous) ---\n";
66            echo "メッセージ: " . $previousException->getMessage() . "\n";
67            echo "コード: " . $previousException->getCode() . "\n";
68            echo "例外タイプ: " . get_class($previousException) . "\n";
69            echo "発生ファイル: " . $previousException->getFile() . " (行: " . $previousException->getLine() . ")\n";
70        } else {
71            echo "\nこの例外には、前の例外（previous）は関連付けられていません。\n";
72        }
73    }
74}
75
76// 例外チェーンのデモンストレーションを実行する
77demonstrateExceptionChaining();

PHPのExceptionクラスが持つpreviousプロパティは、例外チェーンを実装するための重要な要素です。これは、ある例外を捕捉した後に、その例外を原因として新しい上位の例外を発生させる（スローする）際に、元の例外の情報を保持するために利用されます。複雑なアプリケーション開発において、データベース接続の失敗など低レベルで発生したエラーが、レポート生成失敗といった高レベルなエラーとして表面化することがあります。このpreviousプロパティを使用すると、これらのエラー間の関連性を明確にし、問題の根本原因を追跡・特定しやすくなります。PHP 8以降では、Exceptionコンストラクタの第3引数として、前のThrowableオブジェクトを渡すことで、このプロパティに値を設定します。previousプロパティ自身に引数はありません。このプロパティにアクセスすると、設定された前の例外がThrowableオブジェクトとして返されますが、前の例外が関連付けられていない場合はnullが返されます。これにより、エラーの発生源を効率的に特定し、デバッグを支援します。

Copy
1<?php
2
3/**
4 * カスタム例外クラスの例。
5 * アプリケーション固有のエラーを表すために使用されます。
6 */
7class ApplicationProcessingException extends Exception
8{
9    // 特に何も追加しないシンプルな例外クラス
10}
11
12/**
13 * 何らかの操作をシミュレートする関数。
14 * 実際にはファイル操作やデータベースアクセスなど、失敗する可能性のある処理が入ります。
15 *
16 * @throws RuntimeException 内部的な低レベルエラーが発生した場合
17 */
18function performLowLevelOperation(): void
19{
20    // 50%の確率でエラーを発生させるシミュレーション
21    if (rand(0, 1) === 0) {
22        throw new RuntimeException("データベース接続に失敗しました。");
23    }
24    echo "低レベル操作が正常に完了しました。\n";
25}
26
27/**
28 * アプリケーションの主要な処理を実行する関数。
29 * 低レベルなエラーをキャッチし、よりアプリケーション固有の例外として再スローします。
30 *
31 * @throws ApplicationProcessingException アプリケーションレベルのエラーが発生した場合
32 */
33function processApplicationData(): void
34{
35    try {
36        performLowLevelOperation();
37    } catch (RuntimeException $e) {
38        // 低レベルな例外をキャッチし、それを原因として新しいアプリケーション例外をスローします。
39        // 第3引数に元の例外を渡すことで、新しい例外のpreviousプロパティに設定されます。
40        throw new ApplicationProcessingException(
41            "データの処理中に問題が発生しました。",
42            500, // 例: 内部サーバーエラーを示すHTTPステータスコード
43            $e  // 原因となった以前の例外（previous exception）
44        );
45    }
46}
47
48// メインの実行ブロック
49echo "アプリケーション処理を開始します...\n";
50
51try {
52    processApplicationData();
53    echo "アプリケーション処理が正常に完了しました。\n";
54} catch (ApplicationProcessingException $e) {
55    echo "\nエラーが発生しました。\n";
56    echo "  メッセージ: " . $e->getMessage() . "\n";
57    echo "  ファイル: " . $e->getFile() . " (行: " . $e->getLine() . ")\n";
58
59    // Exception::previousプロパティをチェックし、原因となった例外が存在すれば表示します。
60    // PHP 8では戻り値の型が ?Throwable なので、nullチェックが必要です。
61    $previousException = $e->getPrevious();
62    if ($previousException !== null) {
63        echo "\n  元の原因となった例外 (previous exception):\n";
64        echo "    タイプ: " . get_class($previousException) . "\n";
65        echo "    メッセージ: " . $previousException->getMessage() . "\n";
66        echo "    ファイル: " . $previousException->getFile() . " (行: " . $previousException->getLine() . ")\n";
67    }
68} catch (Throwable $e) {
69    // 予期せぬその他の例外をキャッチするフォールバック
70    echo "\n予期せぬ致命的なエラーが発生しました: " . $e->getMessage() . "\n";
71}
72
73echo "\n処理が終了しました。\n";

このPHPのサンプルコードは、例外が複数層で発生した際に、元の例外（原因となった例外）の情報を保持し、後から参照する方法を示しています。Exceptionクラスのpreviousプロパティは、ある例外が発生した原因となった別の例外を格納するためのものです。

コードではまず、低レベルな処理を行うperformLowLevelOperation関数がRuntimeExceptionをスローする可能性があります。次に、processApplicationData関数がこのRuntimeExceptionをキャッチし、よりアプリケーション固有のApplicationProcessingExceptionとして再スローしています。このとき、ApplicationProcessingExceptionのコンストラクタの第3引数にキャッチしたRuntimeExceptionを渡すことで、そのRuntimeExceptionが新しいApplicationProcessingExceptionのpreviousプロパティに設定されます。

メインの実行ブロックでは、ApplicationProcessingExceptionをキャッチした後、$e->getPrevious()メソッドを使って原因となった元の例外を取得しています。このメソッドは引数をとりません。getPrevious()メソッドの戻り値は?Throwable型であり、元の例外が存在しない場合はnullを返すため、nullチェックを行い、元の例外の詳細情報を表示しています。このように元の例外情報を保持することで、エラーの原因究明が容易になります。

Copy
1<?php
2
3// Define custom exceptions for better clarity and specific error handling.
4// QuestionPaperServiceException is a general error from our service.
5class QuestionPaperServiceException extends Exception {}
6// QuestionPaperNotFoundException specifically indicates a missing resource.
7class QuestionPaperNotFoundException extends QuestionPaperServiceException {}
8
9/**
10 * QuestionPaperService manages operations related to fetching previous year question papers.
11 *
12 * This class demonstrates the use of Exception::previous (accessed via getPrevious())
13 * for exception chaining. When an underlying error (like a paper not being found) occurs,
14 * it's caught and re-thrown as a higher-level service exception, preserving the original
15 * cause. This helps system engineers understand the root of an issue.
16 *
17 * The scenario is designed to be relevant to "php previous year question paper rajasthan university".
18 */
19class QuestionPaperService
20{
21    /**
22     * Simulates the retrieval of a previous year's question paper for a given university, year, and subject.
23     * It showcases exception chaining when an expected failure occurs.
24     *
25     * @param string $universityName The name of the university (e.g., 'Rajasthan University').
26     * @param string $year           The academic year of the question paper.
27     * @param string $subject        The subject of the question paper.
28     * @return string The content of the question paper.
29     * @throws QuestionPaperServiceException If any error prevents the retrieval of the paper.
30     */
31    public function getPreviousYearQuestionPaper(
32        string $universityName,
33        string $year,
34        string $subject
35    ): string {
36        echo "Attempting to retrieve {$universityName} {$year} {$subject} paper...\n";
37
38        try {
39            // Simulate an internal data retrieval process.
40            // For demonstration, let's assume 'History' papers for '2023' are specifically
41            // missing or problematic for 'Rajasthan University'.
42            if ($universityName === 'Rajasthan University' && $year === '2023' && $subject === 'History') {
43                // This simulates a lower-level problem, like a database record not found or a file missing.
44                throw new QuestionPaperNotFoundException(
45                    "Paper data for {$universityName} {$year} {$subject} could not be located in the archive."
46                );
47            }
48
49            // Simulate successful retrieval and return some content.
50            $paperContent = "--- {$universityName} {$year} {$subject} Question Paper (Sample) ---\n"
51                          . "Q1. Discuss the key events of {$year} in {$subject} from the perspective of {$universityName}.\n"
52                          . "Q2. Explain the significance of [concept related to subject].";
53
54            return $paperContent;
55
56        } catch (QuestionPaperNotFoundException $e) {
57            // Catch the specific underlying "not found" issue.
58            // Re-throw a higher-level service exception, *chaining* the original 'not found' exception.
59            // This allows the caller to know the specific type of service error, while also
60            // providing access to the precise cause via Exception::getPrevious().
61            throw new QuestionPaperServiceException(
62                "Failed to process request for {$universityName} {$year} {$subject} paper. " .
63                "A required paper was not found.",
64                0, // Optional: custom error code
65                $e // The previous exception (QuestionPaperNotFoundException) is chained here.
66            );
67        } catch (Throwable $e) {
68            // Catch any other unexpected system errors (e.g., database connection issues, file system errors).
69            // Re-throw a generic service exception, *chaining* the original unexpected error.
70            throw new QuestionPaperServiceException(
71                "An unexpected error occurred while fetching the {$universityName} {$year} {$subject} paper.",
72                0,
73                $e // Chain any other unexpected Throwable.
74            );
75        }
76    }
77}
78
79// --- Main execution block to demonstrate the functionality ---
80$service = new QuestionPaperService();
81
82try {
83    // Scenario 1: Successfully retrieve a question paper.
84    $paper1 = $service->getPreviousYearQuestionPaper('Rajasthan University', '2022', 'Computer Science');
85    echo "\nSuccessfully retrieved paper:\n{$paper1}\n";
86
87    // Scenario 2: Attempt to retrieve a paper that is configured to fail,
88    // demonstrating exception chaining for 'Rajasthan University' 2023 History.
89    echo "\n------------------------------------------------\n";
90    echo "Attempting to retrieve a paper that is expected to fail:\n";
91    $paper2 = $service->getPreviousYearQuestionPaper('Rajasthan University', '2023', 'History');
92    // This line will not be reached because an exception will be thrown.
93    echo "\nSuccessfully retrieved paper:\n{$paper2}\n";
94} catch (QuestionPaperServiceException $e) {
95    // This catch block handles the higher-level service exception.
96    echo "\nCaught a QuestionPaperServiceException:\n";
97    echo "Message: " . $e->getMessage() . "\n";
98    echo "Code: " . $e->getCode() . "\n";
99    echo "Stack Trace: \n" . $e->getTraceAsString() . "\n";
100
101    // Accessing the 'previous' exception using getPrevious(), which returns ?Throwable.
102    $previous = $e->getPrevious();
103    if ($previous !== null) {
104        echo "\n--- Original cause (previous exception) ---\n";
105        echo "Class: " . get_class($previous) . "\n";
106        echo "Message: " . $previous->getMessage() . "\n";
107        echo "Stack Trace of Original Cause: \n" . $previous->getTraceAsString() . "\n";
108    } else {
109        echo "\nNo previous exception found for this error (meaning this was the root cause).\n";
110    }
111} catch (Throwable $e) {
112    // This general catch block handles any other unexpected, unhandled Throwables.
113    echo "\nCaught an unexpected general Throwable:\n";
114    echo "Class: " . get_class($e) . "\n";
115    echo "Message: " . $e->getMessage() . "\n";
116    echo "Stack Trace: \n" . $e->getTraceAsString() . "\n";
117}
118
119?>

PHPのExceptionクラスには、ある例外が別の例外の原因となった場合に、その元の例外（previous exception）を内包できる「例外チェイン」という機能があります。この内包された元の例外オブジェクトを取得するために、Exception::previousプロパティ（getPrevious()メソッドを通じてアクセス）が使用されます。getPrevious()メソッドに引数はなく、戻り値はThrowableインターフェースを実装した元の例外オブジェクトか、元の例外が存在しない場合はnullが返されます。

この機能は、システム内部で発生した具体的なエラー（例：データが見つからない）を、システム全体として意味のある上位レベルのエラー（例：サービス処理失敗）として再通知する際に特に役立ちます。これにより、エラーを受け取る側は、表面的なエラーだけでなく、その根本原因まで詳細に把握し、問題解決に繋げることができます。

サンプルコードでは、「ラジャスタン大学の過去問を取得するサービス」を模擬しています。QuestionPaperServiceクラスのgetPreviousYearQuestionPaperメソッド内で、特定の過去問が見つからない場合にQuestionPaperNotFoundExceptionという下位レベルの例外が発生すると想定されています。この下位例外はcatchブロックで捕捉され、それを原因とするQuestionPaperServiceExceptionという上位レベルの例外が新たにスローされます。このとき、QuestionPaperServiceExceptionのコンストラクタの第3引数に元のQuestionPaperNotFoundExceptionを渡すことで、二つの例外がチェインされます。

メインの実行ブロックでは、サービスで発生したQuestionPaperServiceExceptionをcatchした後、$e->getPrevious()を呼び出すことで、サービスエラーの根本原因であるQuestionPaperNotFoundExceptionの詳細（クラス名、メッセージなど）を取得し、表示しています。これにより、過去問が見つけられなかったという具体的な理由まで理解できるため、システムエンジニアはより効率的に問題の根本原因を特定し、対処することが可能となります。