【PHP8.x】ValueError::codeプロパティの使い方

Copy
1<?php
2
3/**
4 * ユーザーから受け取ったデータの処理を模倣し、
5 * 不適切な値が検出された場合にValueErrorをスローする関数。
6 *
7 * この関数は、CodeIgniterのようなWebフレームワークを用いたアプリケーションにおいて、
8 * ユーザー入力のバリデーション中に不適切な値（例: ページングのための負の項目数）が検出された
9 * シナリオを想定しています。
10 *
11 * @param string $inputName 入力フィールドの名前（例: 'items_per_page'）
12 * @param mixed $inputValue 入力された値
13 * @throws ValueError 入力値が不適切である場合
14 * @return string 処理が成功した場合の、文字列に変換された入力値
15 */
16function processValidatedInput(string $inputName, mixed $inputValue): string
17{
18    // 'items_per_page'という入力が、1以上の整数であることを期待すると仮定します。
19    // それ以外の値は不適切としてValueErrorをスローします。
20    if ($inputName === 'items_per_page') {
21        if (!is_int($inputValue) || $inputValue < 1) {
22            // 不適切な値の場合、ValueErrorをスローし、カスタムのエラーコード (1001) を設定します。
23            // ValueErrorのコンストラクタは (メッセージ, コード, 前の例外) の順です。
24            throw new ValueError(
25                "入力 '{$inputName}' は1以上の整数である必要があります。現在の値: " . var_export($inputValue, true),
26                1001 // ここでエラーコードをint型で指定します。
27            );
28        }
29        return (string) $inputValue; // 処理が成功した場合
30    }
31
32    // その他の入力名の場合は、そのまま返す（この例示のため）
33    return (string) $inputValue;
34}
35
36// --- サンプルコードの実行 ---
37
38// 1. 正常なケース: 期待される適切な値を渡す
39echo "--- 正常なケース ---\n";
40try {
41    $processedValue = processValidatedInput('items_per_page', 10);
42    echo "入力 'items_per_page' の処理結果: " . $processedValue . "\n";
43} catch (ValueError $e) {
44    // 正常なケースなので、ここは実行されないはずです。
45    echo "エラーが発生しました (コード: " . $e->getCode() . "): " . $e->getMessage() . "\n";
46}
47
48// 2. 異常なケース: ValueErrorを発生させる値を渡す (0は不適切)
49echo "\n--- 異常なケース (不適切な値: 0) ---\n";
50try {
51    $processedValue = processValidatedInput('items_per_page', 0); // 1未満の値を渡す
52    echo "入力 'items_per_page' の処理結果: " . $processedValue . "\n";
53} catch (ValueError $e) {
54    // ValueErrorを捕捉し、そのメッセージとコードプロパティの値を表示します。
55    echo "エラーが発生しました: " . $e->getMessage() . "\n";
56    // $e->code は例外オブジェクトが持つプロパティで、エラーコード (int型) を返します。
57    echo "取得されたエラーコード: " . $e->getCode() . " (int型)\n"; 
58}
59
60// 3. 別の異常なケース: 不適切な型を渡す ('abc'は整数ではない)
61echo "\n--- 別の異常なケース (不適切な値: 'abc') ---\n";
62try {
63    $processedValue = processValidatedInput('items_per_page', 'abc'); // 整数ではない値を渡す
64    echo "入力 'items_per_page' の処理結果: " . $processedValue . "\n";
65} catch (ValueError $e) {
66    // ValueErrorを捕捉し、そのメッセージとコードプロパティの値を表示します。
67    echo "エラーが発生しました: " . $e->getMessage() . "\n";
68    echo "取得されたエラーコード: " . $e->getCode() . " (int型)\n";
69}

PHPのValueError::codeは、不適切な値が関数に渡された際に発生するValueError例外が持つプロパティです。このcodeプロパティは、発生したエラーの種類を識別するための整数値（int型）を保持します。開発者はValueErrorをスローする際に、このエラーコードを任意に指定でき、エラー発生時にそのコードを取得することで、プログラム的にエラーの種類を判別し、適切な処理を行うことが可能になります。

サンプルコードでは、ウェブアプリケーションにおけるユーザー入力の検証を想定したprocessValidatedInput関数が定義されています。この関数は、items_per_pageという入力が1以上の整数であるかをチェックし、不適切な値（0や文字列など）が検出された場合にValueErrorをスローします。このとき、throw new ValueError(...)の第2引数でカスタムエラーコード1001を設定しています。

try-catchブロックでValueErrorを捕捉すると、例外オブジェクト$eから$e->getCode()メソッド（または直接$e->codeプロパティ）を使って、スローされたエラーコード1001を取得できます。これにより、エラーメッセージとは別に、エラーの種類を数値で特定し、より柔軟なエラーハンドリングを実現できます。このcodeプロパティは引数を取らず、常にint型の数値を返します。

Copy
1<?php
2
3/**
4 * 正の偶数を受け取り、そのまま返します。
5 * 入力値が正の偶数でない場合はValueErrorをスローします。
6 *
7 * この関数は、入力値の検証とそれに関連するエラーハンドリングの例を示し、
8 * ValueError::code プロパティの使用方法を実演します。
9 * PHPの推奨コーディングスタイルに従っています。
10 *
11 * @param int $number 検証する数値。
12 * @return int 入力された正の偶数。
13 * @throws ValueError 数値が条件を満たさない場合、適切なエラーコードを付けてスローします。
14 */
15function processPositiveEvenNumber(int $number): int
16{
17    if ($number <= 0) {
18        // エラーコード1001: 正の数ではない
19        throw new ValueError('入力値は正の数である必要があります。', 1001);
20    }
21
22    if ($number % 2 !== 0) {
23        // エラーコード1002: 偶数ではない
24        throw new ValueError('入力値は偶数である必要があります。', 1002);
25    }
26
27    return $number;
28}
29
30// === サンプルコード実行部分 ===
31
32// ケース1: 有効な入力
33echo "--- ケース1: 有効な入力 ---\n";
34try {
35    $result = processPositiveEvenNumber(10);
36    echo "入力 '10' は有効です。結果: " . $result . "\n\n";
37} catch (ValueError $e) {
38    // このケースではValueErrorは捕捉されません
39    echo "予期せぬValueErrorを捕捉しました:\n";
40    echo "コード: " . $e->code . ", メッセージ: " . $e->getMessage() . "\n\n";
41}
42
43// ケース2: 負の数（エラーコード 1001 を想定）
44echo "--- ケース2: 負の数 ---\n";
45try {
46    processPositiveEvenNumber(-4);
47    echo "この行は実行されません。\n\n"; // エラーでスキップされる
48} catch (ValueError $e) {
49    echo "ValueErrorを捕捉しました:\n";
50    echo "エラーコード: " . $e->code . "\n"; // ValueError::codeプロパティの使用例
51    echo "メッセージ: " . $e->getMessage() . "\n\n";
52}
53
54// ケース3: 奇数（エラーコード 1002 を想定）
55echo "--- ケース3: 奇数 ---\n";
56try {
57    processPositiveEvenNumber(7);
58    echo "この行は実行されません。\n\n"; // エラーでスキップされる
59} catch (ValueError $e) {
60    echo "ValueErrorを捕捉しました:\n";
61    echo "エラーコード: " . $e->code . "\n"; // ValueError::codeプロパティの使用例
62    echo "メッセージ: " . $e->getMessage() . "\n\n";
63}

PHPのValueError::codeプロパティは、プログラムの実行中に発生した値に関するエラー（ValueError）の種類を、数値（int型）で具体的に識別するために利用されます。このプロパティには引数はなく、エラーオブジェクトから直接アクセスすることで、あらかじめ設定されたエラーコードを取得できます。

サンプルコードでは、processPositiveEvenNumber関数が、渡された数値が「正の偶数」であるかを検証しています。もし条件を満たさない場合、ValueErrorをスロー（発生）させますが、このときエラーの種類に応じて1001や1002といった特定のエラーコードを付与しています。例えば、負の数であればコード1001、奇数であればコード1002といった具合です。

これらのエラーはtry-catchブロックで捕捉され、catchブロック内では捕捉したエラーオブジェクト$eから$e->codeとしてプロパティにアクセスすることで、そのエラーがどの条件によって発生したのかを示す数値を読み取ることができます。これにより、開発者はエラーメッセージだけでなく、数値コードによってもエラー原因を明確に判断し、より詳細で適切なエラー処理を行うことが可能になります。サンプルコードの実行部分では、有効な入力と、負の数や奇数といった無効な入力の両方を試し、無効な入力の際にValueError::codeプロパティがどのように利用され、特定のエラーコードが出力されるかを示しています。

Copy
1<?php
2
3/**
4 * PHP 8で導入されたValueErrorのハンドリングと、そのcodeプロパティの利用例を示します。
5 * ValueErrorは、通常、関数の引数の値が期待される型であるが、その値が不正な場合にスローされます。
6 * 例えば、array_rand() 関数に空の配列を渡すなどが該当します。
7 * このような例外処理は、堅牢なPHPアプリケーションを開発する上で重要であり、
8 * PHPの推奨コーディングスタイルに従うことで、CodeSnifferなどの静的解析ツールによる
9 * コード品質のチェックも容易になります。
10 */
11function demonstrateValueErrorHandling(): void
12{
13    echo "--- ValueError Handling Example ---\n";
14
15    try {
16        // PHP 8以降では、array_rand() に空の配列を渡すとValueErrorがスローされます。
17        // ここで意図的にValueErrorを発生させます。
18        array_rand([], 1);
19    } catch (ValueError $e) {
20        // ValueErrorをキャッチし、例外メッセージを出力します。
21        echo "Caught ValueError:\n";
22        echo "  Message: " . $e->getMessage() . "\n";
23
24        // ValueError::code プロパティにアクセスし、int型のエラーコードを取得します。
25        // デフォルトでは0が返されることが多いですが、特定の状況では異なるコードが設定されることもあります。
26        echo "  Error Code: " . $e->getCode() . " (Type: " . gettype($e->getCode()) . ")\n";
27    }
28
29    echo "--- End of Example ---\n";
30}
31
32// 関数を実行して、ValueErrorのハンドリングを実演します。
33demonstrateValueErrorHandling();

このサンプルコードは、PHP 8で導入されたValueError例外の基本的なハンドリングと、そのcodeプロパティ（getCode()メソッドで取得）の利用方法をシステムエンジニアを目指す初心者の方向けに説明します。

ValueErrorは、関数の引数に渡された値が、期待される型ではあるものの、その値自体が不正である場合に発生する例外です。例えば、array_rand()関数に空の配列を渡すと、このValueErrorがスローされます。コードでは、try-catchブロックを使用して、意図的にarray_rand([], 1)でValueErrorを発生させ、それを捕捉しています。

捕捉したValueErrorオブジェクトからは、getMessage()メソッドでエラーの詳細な説明を取得できます。さらに、$e->getCode()を呼び出すことで、この例外に関連付けられたエラーコードを取得することが可能です。ValueError::codeプロパティは引数を取らず、戻り値として常に整数型（int）の値を返します。通常、PHPの組み込みValueErrorでは0が返されることが多いですが、特定の状況下で異なるエラーコードが設定されることもあります。

このような例外ハンドリングを適切に行うことで、プログラムが予期せぬ不正な入力値に対しても堅牢に対応し、安定した動作を保つことができるようになります。

Copy
1<?php
2
3/**
4 * 入力値の有効性を実行時に「チェック」し、不正な値が渡された場合に発生する
5 * ValueError（値エラー）を捕捉して処理するPHPのサンプルコードです。
6 *
7 * この関数は割り算を実行します。特にゼロ除算のような不正な操作を防ぐために
8 * 例外処理を利用しており、システムエンジニアが実行時のエラーハンドリングを学ぶ上で
9 * 重要なパターンを示します。
10 *
11 * @param int $dividend 割られる数 (被除数)
12 * @param int $divisor 割る数 (除数)
13 * @return float|int|null 割り算の結果を返します。不正な入力値によってValueErrorが発生した場合はnullを返します。
14 */
15function performSafeDivision(int $dividend, int $divisor): float|int|null
16{
17    try {
18        // PHPの組み込み関数 intdiv() は、ゼロ除算を試みた場合に ValueError をスローします。
19        // これは、引数の型は正しい（int）が、その値が不正であるケースです。
20        // ここでの try ブロックは、コードが実行される際に値の「チェック」を行う場所と見なせます。
21        $result = intdiv($dividend, $divisor);
22        echo "計算結果: " . $result . PHP_EOL;
23        return $result;
24    } catch (ValueError $e) {
25        // ValueError を捕捉し、エラーの詳細情報を取得・表示します。
26        // $e->getCode() は、この例外の特定の数値コードを返しますが、
27        // 組み込みの ValueError の場合は通常 0 です。
28        // $e->getMessage() は、エラーの具体的な説明を提供します。
29        echo "【実行時エラー検出】不正な値が検出されました！" . PHP_EOL;
30        echo "  エラーメッセージ: " . $e->getMessage() . PHP_EOL;
31        echo "  エラーコード: " . $e->getCode() . " (ValueErrorの組み込みコードは通常0)" . PHP_EOL;
32        echo "  エラー発生ファイル: " . $e->getFile() . PHP_EOL;
33        echo "  エラー発生行: " . $e->getLine() . PHP_EOL;
34        return null;
35    } catch (Throwable $e) {
36        // ValueError以外の、より一般的なエラー（例えば TypeError など）も捕捉できますが、
37        // 今回の主な目的はValueErrorに焦点を当てることです。
38        echo "【予期せぬエラー】タイプ: " . get_class($e) . ", メッセージ: " . $e->getMessage() . PHP_EOL;
39        return null;
40    }
41}
42
43// --- 関数実行例 ---
44
45// 1. 正常な入力値のテスト
46echo "--- 正常な入力値のテスト ---" . PHP_EOL;
47performSafeDivision(10, 2);
48echo PHP_EOL;
49
50// 2. 不正な入力値（ゼロ除算）のテスト
51//    intdiv() は、除数が0の場合に ValueError をスローします。
52echo "--- 不正な入力値 (ゼロ除算) のテスト ---" . PHP_EOL;
53performSafeDivision(10, 0);
54echo PHP_EOL;
55
56// 3. 別の正常な入力値のテスト
57echo "--- 別の正常な入力値のテスト ---" . PHP_EOL;
58performSafeDivision(15, 3);
59echo PHP_EOL;

このPHPサンプルコードは、プログラムの実行中に渡された値が有効かどうかを「チェック」し、不正な値が検出された場合に発生するValueError（値エラー）を安全に処理する方法を示しています。特にシステムエンジニアが実行時のエラーハンドリングを学ぶ上で重要なパターンです。

performSafeDivision関数は二つの整数$dividend（割られる数）と$divisor（割る数）を引数として受け取り、割り算を実行します。この関数では、tryブロック内でintdiv()関数を使って割り算を試みており、ここでゼロ除算のような不正な値の「チェック」が行われます。

もし$divisorにゼロが渡されると、intdiv()関数はValueErrorをスローします。このエラーはcatch (ValueError $e)ブロックで捕捉され、プログラムが予期せず停止するのを防ぎます。捕捉されたエラーオブジェクト$eから、$e->getCode()プロパティを使ってエラーに紐づく数値コードを整数で取得できます。ValueErrorのような組み込みの例外の場合、このコードは通常0を返します。これにより、エラーの種類や原因を詳細に把握し、適切なメッセージ表示や処理を行うことが可能になります。関数の戻り値は、正常な場合は計算結果のfloatまたはint、エラー発生時はnullとなります。