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

Copy
1<?php
2
3/**
4 * PHPのFILTER_REQUIRE_ARRAY定数の使用例を示します。
5 *
6 * この関数は filter_input_array() を使用し、$_GETスーパーグローバル変数を模擬して
7 * 特定の入力が配列であることを必須とするフィルタリングの挙動をデモンストレーションします。
8 *
9 * システムエンジニアを目指す初心者にも理解しやすいように、簡潔で正確なコードを提供します。
10 *
11 * @return array フィルタリングされたデータ（成功例と失敗例を含む）
12 */
13function demonstrateFilterRequireArray(): array
14{
15    // フィルタリング定義: 'ids' は整数配列を必須とし、'name' は一般的な文字列を許可
16    $filters = [
17        'ids' => [
18            'filter'  => FILTER_VALIDATE_INT, // 各要素を整数として検証
19            // FILTER_FORCE_ARRAY は、たとえ単一値であっても配列として扱うことを試みる
20            // FILTER_REQUIRE_ARRAY は、入力自体が配列でなければ検証を失敗させる
21            'flags'   => FILTER_FORCE_ARRAY | FILTER_REQUIRE_ARRAY,
22            'options' => ['min_range' => 1] // 1以上の整数のみを許可
23        ],
24        'name' => [
25            'filter' => FILTER_UNSAFE_RAW, // 未加工のデータを許可
26            'flags'  => FILTER_FLAG_STRIP_LOW // 不可視文字などを除去
27        ]
28    ];
29
30    // --- ケース1: 'ids' が期待通り配列として与えられた場合（成功例） ---
31    // $_GET スーパーグローバル変数を一時的に設定して Web リクエストを模擬します。
32    $_GET = ['ids' => ['10', '20'], 'name' => 'Alice'];
33    $filteredDataSuccess = filter_input_array(INPUT_GET, $filters);
34    /*
35     * このケースでの $filteredDataSuccess の期待される内容:
36     * [
37     *   "ids" => [10, 20],
38     *   "name" => "Alice"
39     * ]
40     * 'ids' は配列であり、各要素が整数として検証され、成功します。
41     */
42
43    // --- ケース2: 'ids' が配列ではない文字列として与えられた場合（FILTER_REQUIRE_ARRAY により失敗） ---
44    // $_GET スーパーグローバル変数を更新して、別のシナリオを模擬します。
45    $_GET = ['ids' => '30', 'name' => 'Bob']; // 'ids' が単一の文字列
46    $filteredDataFailure = filter_input_array(INPUT_GET, $filters);
47    /*
48     * このケースでの $filteredDataFailure の期待される内容:
49     * [
50     *   "ids" => false, // FILTER_REQUIRE_ARRAY が設定されているため、入力が配列でないと検証は失敗します。
51     *   "name" => "Bob"
52     * ]
53     * 'ids' は配列ではないため、検証全体が失敗し、false となります。
54     */
55
56    // グローバル変数の汚染を防ぐため、$_GET をリセットします。
57    $_GET = [];
58
59    // 両方の結果を配列で返します。
60    return [
61        'success_case' => $filteredDataSuccess,
62        'failure_case' => $filteredDataFailure,
63    ];
64}
65
66// 関数を呼び出すことで、上記でシミュレートしたフィルタリングの結果を得ることができます。
67// 例えば、以下のように結果を確認できますが、このコードブロックの出力には含めません。
68// $results = demonstrateFilterRequireArray();
69// var_dump($results['success_case']);
70// var_dump($results['failure_case']);
71

PHPのFILTER_REQUIRE_ARRAY定数は、filter_input_arrayなどのフィルタリング関数で使用するフラグです。この定数自体に引数や戻り値はありませんが、入力データの検証ルールを細かく設定するために利用されます。

この定数をフィルタリングの定義に含めることで、対象の入力データが必ず配列であることを強制できます。もしフィルタリングの対象となる入力が配列ではない場合、たとえFILTER_VALIDATE_INTのような他の検証ルールが設定されていても、そのフィールドのフィルタリングは失敗し、結果としてfalseが返されます。

提供されたサンプルコードでは、filter_input_array関数を使ってWebリクエストの$_GETデータをシミュレートし、'ids'という入力に対するフィルタリングの挙動をデモンストレーションしています。'ids'のフィルタ定義にはFILTER_REQUIRE_ARRAYフラグが設定されています。

最初の成功例では、'ids'が['10', '20']という配列で与えられているため、各要素が整数として検証され、[10, 20]という結果が得られます。しかし、失敗例として'ids'が'30'という単一の文字列で与えられた場合、FILTER_REQUIRE_ARRAYの要件を満たさないため、'ids'のフィルタリング結果はfalseとなります。

このように、FILTER_REQUIRE_ARRAYは、特定の入力が配列形式であることを厳密に求め、不正な形式のデータを排除するのに役立ちます。filter_input_arrayは、定義されたフィルタリングルールに基づいて検証されたデータを連想配列として返します。

Copy
1<?php
2
3/**
4 * PHPのFILTER_REQUIRE_ARRAY定数を使用した、URLクエリパラメータからの配列データ取得例。
5 *
6 * FILTER_REQUIRE_ARRAY は、filter_input() や filter_var() 関数でオプションとして使用され、
7 * 対象の入力値が配列であることを強制するフラグです。
8 * 入力値が配列でない場合、フィルター処理は失敗し、false を返します。
9 *
10 * システムエンジニアを目指す初心者向けに、以下のURL例で動作を確認できます:
11 *   1. 成功例 (入力が配列):
12 *      http://localhost/your_script.php?items[]=apple&items[]=orange&items[]=banana
13 *   2. 失敗例 (入力が配列ではない):
14 *      http://localhost/your_script.php?items=single_item
15 *   3. パラメータが存在しない例:
16 *      http://localhost/your_script.php
17 */
18function getArrayInputWithFilterRequireArray(): void
19{
20    echo "<h1>FILTER_REQUIRE_ARRAY の使用デモンストレーション</h1>";
21
22    // URLクエリパラメータから 'items' を取得します。
23    // INPUT_GET: GETメソッドで送信されたデータを対象とします。
24    // 'items': 取得したいパラメータの名前です。
25    // FILTER_DEFAULT: デフォルトのフィルターで、通常は文字列として扱います。
26    // ['options' => FILTER_REQUIRE_ARRAY]: フィルターオプションを指定します。
27    //   FILTER_REQUIRE_ARRAY を含めることで、入力が配列であることを必須とします。
28    $items = filter_input(INPUT_GET, 'items', FILTER_DEFAULT, ['options' => FILTER_REQUIRE_ARRAY]);
29
30    echo "<h2>'items' パラメータの処理結果:</h2>";
31
32    if ($items === false) {
33        // filter_input() が false を返した場合:
34        // これは、入力 'items' が配列ではない、または他のフィルター要件を満たさなかったことを示します。
35        echo "<p><strong>結果: false</strong> - 入力 'items' は配列ではありませんでした、または検証に失敗しました。</p>";
36        echo "<p>ヒント: URLに <code>items[]=value1&items[]=value2</code> の形式でパラメータを追加して試してください。</p>";
37    } elseif ($items === null) {
38        // filter_input() が null を返した場合:
39        // これは、URLに 'items' パラメータ自体が存在しないことを示します。
40        echo "<p><strong>結果: null</strong> - URLに 'items' パラメータが指定されていません。</p>";
41        echo "<p>ヒント: URLに <code>items[]=value1&items[]=value2</code> または <code>items=value</code> の形式でパラメータを追加して試してください。</p>";
42    } else {
43        // filter_input() が配列を返した場合:
44        // 成功した場合、$items は期待通り配列として取得されます。
45        echo "<p><strong>結果: 配列</strong> - 取得されたデータ:</p>";
46        echo "<pre>";
47        print_r($items);
48        echo "</pre>";
49
50        // 取得された配列の各要素とその型を表示し、内容を理解しやすくします。
51        if (is_array($items) && !empty($items)) {
52            echo "<p>配列内の各要素の型:</p>";
53            foreach ($items as $key => $value) {
54                echo "<code>Key: " . htmlspecialchars((string)$key) . ", Value: " . htmlspecialchars((string)$value) . ", Type: " . gettype($value) . "</code><br>";
55            }
56        }
57    }
58}
59
60// デモンストレーション関数を実行します。
61getArrayInputWithFilterRequireArray();
62

PHP 8で利用可能なFILTER_REQUIRE_ARRAYは、filter_input()やfilter_var()関数などの入力値フィルタリング処理において、対象の入力が配列であることを強制するための定数です。この定数自体に引数や戻り値はありませんが、フィルタリング関数のオプションとして利用することで、入力値の検証挙動を制御します。

サンプルコードでは、URLクエリパラメータからitemsという名前の配列データを取得する際にFILTER_REQUIRE_ARRAYを使用しています。filter_input(INPUT_GET, 'items', FILTER_DEFAULT, ['options' => FILTER_REQUIRE_ARRAY])のように指定することで、GETリクエストのitemsパラメータが配列形式であることを必須とします。

もしURLにitems[]=value1&items[]=value2のように配列としてデータが渡された場合、フィルタリングは成功し、itemsは期待通り配列として取得されます。しかし、items=single_itemのように配列ではない単一の値が渡された場合、FILTER_REQUIRE_ARRAYの条件を満たさないため、filter_input()関数はfalseを返します。これは、入力が配列であるという要件が満たされなかったことを意味します。

また、URLにitemsパラメータ自体が存在しない場合は、filter_input()関数はnullを返します。このサンプルコードは、成功、入力が配列ではない失敗、パラメータが存在しない場合の3つのケースを具体的に示し、それぞれの処理結果を確認できます。FILTER_REQUIRE_ARRAYを利用することで、Webアプリケーションにおいて、外部からの入力値が想定通りの配列形式であることを確実に検証し、より安全で堅牢なシステムを構築するための重要な手法となります。