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

Copy
1<?php
2
3/**
4 * FILTER_REQUIRE_SCALAR の動作を理解するためのサンプル関数。
5 *
6 * この関数は、filter_var() 関数と FILTER_REQUIRE_SCALAR 定数を組み合わせて、
7 * 入力値が配列ではないスカラー値であることを強制する挙動を示します。
8 * システムエンジニアを目指す初心者の方のために、各ステップと結果を分かりやすく出力します。
9 *
10 * FILTER_REQUIRE_SCALAR は、filter_var() のオプションとして使用され、
11 * 入力値が文字列、整数、浮動小数点数、真偽値のような単一のスカラー値である場合にのみ
12 * フィルタリングを続行させます。もし入力値が配列であった場合、
13 * 検証は即座に失敗し、false を返します。
14 *
15 * @param mixed $value フィルタリングを試みる入力値
16 * @return mixed フィルタリングされた値、またはフィルタリングが失敗した場合は false
17 */
18function demonstrateFilterRequireScalar(mixed $value): mixed
19{
20    echo "--- フィルタリングの試行 ---\n";
21    echo "  入力値の型: " . gettype($value) . "\n";
22    echo "  入力値: " . (is_array($value) ? json_encode($value) : var_export($value, true)) . "\n";
23
24    // filter_var() 関数を使用し、FILTER_VALIDATE_INT で整数として検証します。
25    // オプションとして FILTER_REQUIRE_SCALAR を指定することで、
26    // 入力値が配列ではないスカラー値であることを強制します。
27    // もし $value が配列だった場合、FILTER_VALIDATE_INT の検証が行われる前に false が返されます。
28    $filteredValue = filter_var($value, FILTER_VALIDATE_INT, FILTER_REQUIRE_SCALAR);
29
30    if ($filteredValue === false) {
31        // filter_var() が false を返すのは、主に以下のいずれかの場合です。
32        // 1. 入力値が FILTER_REQUIRE_SCALAR によって配列であると判断された。
33        // 2. 入力値がスカラー値ではあったが、FILTER_VALIDATE_INT の検証に失敗した（例: "abc"）。
34        echo "  結果: false\n";
35        echo "  理由: ";
36        if (is_array($value)) {
37            echo "入力値が配列であるため、FILTER_REQUIRE_SCALAR によって検証が拒否されました。\n";
38        } elseif (!is_scalar($value)) {
39             echo "入力値がスカラー値ではないため、FILTER_REQUIRE_SCALAR によって検証が拒否されました。\n";
40        } else {
41            echo "入力値はスカラー値ですが、整数としての検証 (FILTER_VALIDATE_INT) に失敗しました。\n";
42        }
43    } else {
44        echo "  結果: " . var_export($filteredValue, true) . " (フィルタリング成功)\n";
45        echo "  理由: 入力値はスカラー値であり、かつ整数としての検証に成功しました。\n";
46    }
47    echo "---------------------------------\n\n";
48    return $filteredValue;
49}
50
51// --- フィルタリングの実行例 ---
52
53// 1. 正常なスカラー値の例 (整数)
54demonstrateFilterRequireScalar(123);
55
56// 2. 正常なスカラー値の例 (文字列だが整数に変換可能)
57demonstrateFilterRequireScalar("456");
58
59// 3. スカラー値だが検証に失敗する例 (整数ではない文字列)
60demonstrateFilterRequireScalar("hello");
61
62// 4. スカラー値だが検証に失敗する例 (真偽値 - 整数ではないと判断される)
63demonstrateFilterRequireScalar(true);
64
65// 5. **FILTER_REQUIRE_SCALAR が機能する配列の例**
66//    入力が配列であるため、フィルタリングは即座に失敗し false を返します。
67demonstrateFilterRequireScalar([1, 2, 3]);
68
69// 6. 配列の別の例
70demonstrateFilterRequireScalar(["key" => "value"]);
71
72// 7. 空の配列の例
73demonstrateFilterRequireScalar([]);
74
75// 8. null の例 (スカラー値ではないと判断されるため、FILTER_REQUIRE_SCALAR で拒否されます)
76demonstrateFilterRequireScalar(null);

PHP 8の定数FILTER_REQUIRE_SCALARは、主にfilter_var()関数のオプションとして使用され、入力値が配列ではない単一のスカラー値（文字列、整数、浮動小数点数、真偽値）であることを強制する役割を持ちます。この定数を指定すると、filter_var()はまず入力値が配列ではないことを確認し、もし入力値が配列であった場合は、後続のフィルタリング（例えば、整数への変換や検証）を行うことなく、即座にfalseを返します。また、nullのようにスカラー値ではない入力も、この定数によって拒否されます。これにより、システムが配列を受け入れるべきではない場所で意図しない配列の入力を未然に防ぎ、アプリケーションの安定性やセキュリティを高めることができます。

サンプルコードのdemonstrateFilterRequireScalar関数は、このFILTER_REQUIRE_SCALARの動作を具体的に示しています。この関数は$valueという任意の型の入力値を受け取り、filter_var()とFILTER_VALIDATE_INT、そしてFILTER_REQUIRE_SCALARを組み合わせてフィルタリングを試みます。戻り値は、フィルタリングが成功して整数に変換された値か、検証に失敗した場合（入力が配列、null、または整数として無効なスカラー値だった場合）のfalseです。123のような正常なスカラー値や、[1, 2, 3]のような配列、nullなど、様々な入力に対するFILTER_REQUIRE_SCALARの挙動が、出力メッセージとともに分かりやすく解説されています。

Copy
1<?php
2
3/**
4 * 指定された値が有効な浮動小数点数であるか、かつスカラー値であることを検証します。
5 *
6 * FILTER_VALIDATE_FLOAT は浮動小数点数を検証するフィルターです。
7 * FILTER_REQUIRE_SCALAR は、入力値がスカラー型（数値、文字列、真偽値など）
8 * である場合にのみ検証を続行し、配列やオブジェクトなどの非スカラー値の場合は
9 * 即座に検証を失敗させるフラグです。
10 * (注: FILTER_VALIDATE_FLOAT 自体、非スカラー値を渡されると通常は false を返しますが、
11 * このフラグはより明確にスカラー値であることを要求する場合に使用します。)
12 *
13 * @param mixed $value 検証する値。
14 * @return float|false 有効な浮動小数点数の場合はその値、それ以外の場合は false を返します。
15 */
16function validateFloatWithScalarRequirement(mixed $value): float|false
17{
18    return filter_var(
19        $value,
20        FILTER_VALIDATE_FLOAT,
21        ['flags' => FILTER_REQUIRE_SCALAR]
22    );
23}
24
25// --- 以下は動作確認のためのサンプルコードです ---
26
27// 有効な浮動小数点数のテストケース
28$validFloatString = "123.45";
29$validFloatNumber = 67.89;
30$validNegativeFloat = "-0.123";
31$validExponential = "1.23e-5";
32
33echo "--- 有効な浮動小数点数のテスト ---\n";
34echo "値: '{$validFloatString}' -> 結果: " . var_export(validateFloatWithScalarRequirement($validFloatString), true) . "\n";
35echo "値: {$validFloatNumber} -> 結果: " . var_export(validateFloatWithScalarRequirement($validFloatNumber), true) . "\n";
36echo "値: '{$validNegativeFloat}' -> 結果: " . var_export(validateFloatWithScalarRequirement($validNegativeFloat), true) . "\n";
37echo "値: '{$validExponential}' -> 結果: " . var_export(validateFloatWithScalarRequirement($validExponential), true) . "\n\n";
38
39// 無効な浮動小数点数のテストケース (スカラー値だが書式が不正)
40$invalidFloatString = "hello";
41$invalidFloatWithLetters = "12.3a";
42
43echo "--- 無効な浮動小数点数のテスト (スカラー値) ---\n";
44echo "値: '{$invalidFloatString}' -> 結果: " . var_export(validateFloatWithScalarRequirement($invalidFloatString), true) . "\n";
45echo "値: '{$invalidFloatWithLetters}' -> 結果: " . var_export(validateFloatWithScalarRequirement($invalidFloatWithLetters), true) . "\n\n";
46
47// 非スカラー値のテストケース (FILTER_REQUIRE_SCALAR の効果を確認)
48$arrayValue = [1.23];
49$objectValue = new stdClass();
50$nullValue = null;
51
52echo "--- 非スカラー値のテスト (FILTER_REQUIRE_SCALAR の効果) ---\n";
53echo "値: " . var_export($arrayValue, true) . " (配列) -> 結果: " . var_export(validateFloatWithScalarRequirement($arrayValue), true) . "\n";
54echo "値: (object) -> 結果: " . var_export(validateFloatWithScalarRequirement($objectValue), true) . "\n";
55echo "値: " . var_export($nullValue, true) . " (null) -> 結果: " . var_export(validateFloatWithScalarRequirement($nullValue), true) . "\n";

このPHPサンプルコードは、filter_var関数を利用して、指定された値が有効な浮動小数点数であり、かつスカラー値であることを厳密に検証する方法を示しています。filter_var関数は、変数をフィルタリングするための汎用的な関数です。

validateFloatWithScalarRequirement関数では、検証したい値を$valueとして受け取ります。filter_var関数の第二引数にはFILTER_VALIDATE_FLOATを指定しており、これにより入力値が浮動小数点数として妥当であるかがチェックされます。さらに、第三引数のオプション配列でflagsとしてFILTER_REQUIRE_SCALARを設定しています。このFILTER_REQUIRE_SCALARは、入力値が数値、文字列、真偽値などのスカラー型である場合にのみ検証を続行させ、配列やオブジェクトなどの非スカラー値が渡された場合には、即座に検証を失敗させるためのフラグです。

この組み合わせにより、関数は入力値がスカラー型であることと有効な浮動小数点数であることの両方を満たしているかを厳しく検証します。検証が成功した場合はその浮動小数点数を返し、失敗した場合はfalseを返します。サンプルコードでは、有効な浮動小数点数、書式が不正なスカラー値、そして配列やオブジェクトなどの非スカラー値のそれぞれについて検証を行い、FILTER_REQUIRE_SCALARフラグによって非スカラー値の検証が失敗することを確認しています。