【PHP8.x】UnexpectedValueException::lineプロパティの使い方

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 受け取ったデータが文字列であるか検証する関数。
7 * 文字列でない場合、UnexpectedValueException をスローします。
8 *
9 * @param mixed $data 検証するデータ
10 * @return string 検証済みのデータ
11 * @throws UnexpectedValueException データが文字列でない場合
12 */
13function validateStringData(mixed $data): string
14{
15    if (!is_string($data)) {
16        // 想定外のデータ型が渡されたため、例外をスローします。
17        // この例外がスローされた行の番号が、catchブロックで取得されます。
18        throw new UnexpectedValueException('データは文字列である必要があります。');
19    }
20    return $data;
21}
22
23// --- メイン処理 ---
24
25try {
26    // わざと不正なデータ型（整数）を渡し、例外を発生させます。
27    $processedData = validateStringData(12345);
28    echo "検証に成功しました: " . htmlspecialchars($processedData, ENT_QUOTES, 'UTF-8') . PHP_EOL;
29} catch (UnexpectedValueException $e) {
30    // スローされた例外をここでキャッチします。
31
32    // $e->getLine() を使って、例外が発生したソースコードの行番号を取得します。
33    $errorLine = $e->getLine();
34    $errorMessage = $e->getMessage();
35    $errorFile = $e->getFile();
36
37    // 取得した行番号を含むエラー情報を整形します。
38    $logMessage = sprintf(
39        "[ERROR] File: %s, Line: %d, Message: %s",
40        $errorFile,
41        $errorLine,
42        $errorMessage
43    );
44
45    // 本来はログファイルや外部サービスにエラー情報を「送信」しますが、
46    // このサンプルでは、標準エラー出力に表示することでその処理を代用します。
47    error_log($logMessage);
48
49    // ユーザー向けにエラーが発生したことを通知します。
50    echo "処理中に予期せぬエラーが発生しました。詳細はログを確認してください。" . PHP_EOL;
51}

このPHPサンプルコードは、UnexpectedValueException が発生した際に、その原因となったソースコードの行番号を取得する方法を示しています。エラー発生箇所の特定は、プログラムの問題を修正する上で非常に重要です。

コードの中心は try-catch ブロックです。まず try ブロック内で、文字列を期待する validateStringData 関数に対し、意図的に整数 12345 を渡しています。この関数は、引数が文字列でない場合に UnexpectedValueException という種類の例外を throw (スロー) するように作られています。

例外がスローされると、処理は catch ブロックに移ります。ここで、キャッチした例外オブジェクト $e の getLine() メソッドを呼び出します。このメソッドは引数を取らず、例外が throw されたソースコードの行番号を整数で返します。サンプルでは、この行番号をファイル名やエラーメッセージと組み合わせて、詳細なログメッセージを生成しています。

生成されたログメッセージは、本来ログファイルへの書き出しや外部の監視システムへ「送信」されますが、このコードでは error_log 関数を使って標準エラー出力に表示することで、その処理を代用しています。このように getLine() を利用することで、エラーが発生した正確な位置を突き止め、迅速なデバッグに繋げることができます。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 外部システムから受け取ったデータの形式を検証するクラス。
7 */
8class DataValidator
9{
10    /**
11     * ユーザーIDの形式を検証します。
12     * 'UID-'で始まらないIDは予期せぬ値として例外をスローします。
13     *
14     * @param string $userId 検証するユーザーID
15     * @return void
16     * @throws UnexpectedValueException 形式が不正な場合にスローされます
17     */
18    public function validateUserId(string $userId): void
19    {
20        if (!str_starts_with($userId, 'UID-')) {
21            // 予期せぬ値が渡されたため、例外をスローします。
22            // この例外が発生した行番号が `line` プロパティに格納されます。
23            throw new UnexpectedValueException("ユーザーIDの形式が不正です: {$userId}");
24        }
25        echo "ユーザーID '{$userId}' は正常です。" . PHP_EOL;
26    }
27}
28
29$validator = new DataValidator();
30
31try {
32    // 正常な形式のIDでメソッドを呼び出す
33    $validator->validateUserId('UID-12345');
34
35    // 不正な形式のIDを渡し、意図的に例外を発生させる
36    $validator->validateUserId('INVALID-999');
37
38} catch (UnexpectedValueException $e) {
39    // catchブロックで例外オブジェクトを受け取ります。
40    // ここで、例外情報と外部のログシステムなどを「連携」させる処理を想定します。
41
42    // $e->getLine() を使って、例外がスローされた行番号を取得します。
43    // これは UnexpectedValueException の `line` プロパティの値に相当します。
44    $errorLine = $e->getLine();
45    $errorMessage = $e->getMessage();
46    $errorFile = $e->getFile();
47
48    // 取得した行番号 (`line`) を含むエラー情報を整形して出力します。
49    // このように、発生した問題の箇所を特定するために `line` の情報が利用されます。
50    $logMessage = sprintf(
51        "[ERROR] File: %s, Line: %d, Message: %s",
52        $errorFile,
53        $errorLine,
54        $errorMessage
55    );
56
57    // 生成したログメッセージを出力（実際にはログファイルなどに書き込む）
58    echo $logMessage . PHP_EOL;
59}

このPHPサンプルコードは、UnexpectedValueExceptionクラスが持つlineプロパティの役割を解説するものです。lineプロパティは、プログラムの実行中に例外がスローされたソースコード上の行番号を保持します。

コード内のDataValidatorクラスは、外部システムとの連携を想定し、受け取ったデータの形式を検証します。validateUserIdメソッドは、引数で渡されたユーザーIDが指定の形式に合わない場合にUnexpectedValueExceptionをスローします。例外がthrowされると、その瞬間の行番号が自動的に例外オブジェクトのlineプロパティに格納されます。

try...catchブロックでは、発生した例外を捕捉します。catchブロック内で、例外オブジェクト$eに対してgetLine()メソッドを呼び出すことで、lineプロパティの値を取得できます。このgetLine()メソッドは引数を取らず、戻り値として例外発生箇所の行番号を整数(int)で返します。

サンプルコードでは、この行番号をファイル名やエラーメッセージと組み合わせて、ログとして出力しています。このようにlineプロパティを利用することで、エラーが発生した正確な場所を特定でき、デバッグやログシステムとの連携において非常に重要な情報となります。