【PHP8.x】FILTER_NULL_ON_FAILURE定数の使い方

Copy
1<?php
2
3/**
4 * filter_var 関数で FILTER_NULL_ON_FAILURE フラグを使用した際の動作を示すサンプルです。
5 *
6 * この関数は、指定された値を整数としてフィルタリングします。
7 * FILTER_NULL_ON_FAILURE フラグを使用すると、フィルタリングが失敗した場合に
8 * 従来の false ではなく null を返すようになります。
9 * これは、成功時には整数、失敗時には null というように、
10 * 戻り値の型によって成功と失敗を明確に区別したい場合に特に有用です。
11 *
12 * @param mixed $value フィルタリングする値。
13 * @param bool $useNullOnFailure trueの場合、FILTER_NULL_ON_FAILURE フラグを filter_var に渡します。
14 * @return int|null|false フィルタリングされた整数、フィルタリング失敗時は null (フラグ使用時) または false (フラグ不使用時)。
15 */
16function demonstrateFilterBehavior(mixed $value, bool $useNullOnFailure): int|null|false
17{
18    // 整数フィルタリングのためのオプションを設定
19    $options = [
20        'options' => [
21            'min_range' => 0,   // 0未満の数値は無効とする
22            'max_range' => 100, // 100を超える数値は無効とする
23        ]
24    ];
25
26    // FILTER_NULL_ON_FAILURE フラグの有無に応じてメッセージを切り替え
27    if ($useNullOnFailure) {
28        // フラグを使用する場合、`flags` オプションに追加
29        $options['flags'] = FILTER_NULL_ON_FAILURE;
30        echo "値 '{$value}' をフィルタリング (FILTER_NULL_ON_FAILURE 使用):\n";
31    } else {
32        echo "値 '{$value}' をフィルタリング (FILTER_NULL_ON_FAILURE 不使用):\n";
33    }
34
35    // filter_var 関数を使用して値をフィルタリング
36    // FILTER_VALIDATE_INT は、値が有効な整数であるかをチェックします。
37    $filteredValue = filter_var($value, FILTER_VALIDATE_INT, $options);
38
39    // フィルタリング結果とその型を表示し、初心者にも理解しやすくする
40    echo "  結果: ";
41    if (is_int($filteredValue)) {
42        echo $filteredValue . " (型: int)\n";
43    } elseif ($filteredValue === null) {
44        echo "null (型: null)\n";
45    } elseif ($filteredValue === false) {
46        echo "false (型: bool)\n";
47    } else {
48        // 予期せぬ戻り値があった場合のために、念のため出力
49        echo "(不明な戻り値) " . var_export($filteredValue, true) . " (型: " . gettype($filteredValue) . ")\n";
50    }
51    echo "\n"; // 見やすくするために改行
52    
53    return $filteredValue;
54}
55
56// --- サンプルコードの実行例 ---
57
58echo "--- フィルタリング成功のケース ---\n";
59// 有効な整数値の場合、フラグの有無に関わらず結果は同じ
60demonstrateFilterBehavior("42", false); // "42" は有効な整数 (0～100の範囲内) -> int(42)
61demonstrateFilterBehavior("42", true);  // "42" は有効な整数 (0～100の範囲内) -> int(42)
62
63echo "--- フィルタリング失敗のケース (無効な入力値: 型が異なる) ---\n";
64// "hello" は整数ではないため、フィルタリング失敗
65demonstrateFilterBehavior("hello", false); // FILTER_NULL_ON_FAILURE 不使用 -> bool(false)
66demonstrateFilterBehavior("hello", true);  // FILTER_NULL_ON_FAILURE 使用    -> null
67
68echo "--- フィルタリング失敗のケース (無効な入力値: 範囲外) ---\n";
69// "150" は100を超えるため、フィルタリング失敗
70demonstrateFilterBehavior("150", false);   // FILTER_NULL_ON_FAILURE 不使用 -> bool(false)
71demonstrateFilterBehavior("150", true);    // FILTER_NULL_ON_FAILURE 使用    -> null
72
73// "-5" は0未満のため、フィルタリング失敗
74demonstrateFilterBehavior("-5", false);    // FILTER_NULL_ON_FAILURE 不使用 -> bool(false)
75demonstrateFilterBehavior("-5", true);     // FILTER_NULL_ON_FAILURE 使用    -> null
76
77?>

PHP 8で導入されたFILTER_NULL_ON_FAILURE定数は、データのフィルタリングを行うfilter_var関数と組み合わせて使用される特別なフラグです。通常、filter_var関数で値のフィルタリングが失敗した場合、戻り値はブール値のfalseとなります。しかし、このFILTER_NULL_ON_FAILURE定数をfilter_var関数のフラグとして指定すると、フィルタリング失敗時の戻り値がfalseではなくnullに変わります。

この定数を使用する主なメリットは、成功時には期待する型（例えば整数）、失敗時にはnullというように、戻り値の型によって処理の成否を明確に区別できる点にあります。従来のfalseは有効な数値0と混同される可能性がありましたが、nullを返すことで、このような曖昧さを避けることができます。

サンプルコードのdemonstrateFilterBehavior関数は、この挙動を具体的に示しています。例えば、有効な整数値「42」をフィルタリングした場合、フラグの有無にかかわらず、整数値42が戻り値となります。しかし、「hello」のような無効な文字列や、指定された範囲外の数値「150」をフィルタリングした場合、FILTER_NULL_ON_FAILUREフラグを使用しないとfalseが返されるのに対し、フラグを使用するとnullが返されることが確認できます。

この定数を活用することで、データ検証の結果をより明確かつ厳密に処理できるようになり、エラーハンドリングの精度を高め、堅牢なシステムを開発する上で非常に有用です。