filter_input_array

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

filter_input_array — 外部から変数を受け取り、オプションでそれらをフィルタリングする

説明

function filter_input_array(int $type, array|int $options = FILTER_DEFAULT, bool $add_empty = true): array|false|null

この関数を使用すると、大量のデータを取得する際に filter_input() を繰り返しコールする必要がなくなるので便利です。

パラメータ

type

定数 INPUT_* のうちのひとつ。

警告

フィルタされるスーパーグローバルの内容は、ユーザーがスーパーグローバルに手を加える前の、 SAPI が提供する "生の" ものです。変更されたスーパーグローバルの値をフィルタするには、 filter_var_array() を代わりに使います。

options

オプションの連想配列、または、エントリごとに適用するフィルタ。フィルタは検証フィルタ FILTER_VALIDATE_* または除去フィルタ FILTER_SANITIZE_* が使えます。

オプションの配列は、入力配列に存在するキーをキーとして持つ連想配列で、キーに対応する値には、そのエントリに適用するフィルタ、または、そのエントリにどのフィルタを、どのように適用するかを記述した連想配列のいずれかを指定します。

どのようにフィルタを適用するかを連想配列に記述する場合、どのフィルタを対応する値に適用するかを 'filter' キーに含めなければいけません。 'filter' キーに指定できるのは、 FILTER_VALIDATE_*, FILTER_SANITIZE_*, FILTER_UNSAFE_RAW, FILTER_CALLBACK のうちのいずれかです。オプションで 'flags' キーには、フィルタに適用するフラグを指定できますし、 'options' には、フィルタに適用するオプションを指定できます。

add_empty

返り値の配列に対して、キーが存在しない場合に null を追加します。

戻り値

成功した場合は要求された変数の値を含む配列。

失敗した場合、false を返します。 type で指定された入力配列に値が入っていない場合は、代わりに null を返します。

入力配列に欠けているエントリは、 add_empty が true の場合は返される配列に null として追加され、 false の場合は一切含まれません。 filter_input() とは異なり、 FILTER_NULL_ON_FAILURE フラグを使ってもこの動作は変わらず、欠けているエントリは常に null になります。

フィルタが失敗した場合、返される配列のエントリは false になります。但し、FILTER_NULL_ON_FAILURE フラグを使った場合は null になります。 FILTER_FORCE_ARRAY フラグを使った場合は、この失敗時の値も、ほかの結果と同様に要素を一つ持つ配列でラップされます。

例

例1 filter_input_array() の例

この例では、 ?email=user@example.com&age=twenty&url=https://example.com への GET リクエストを想定しています。 twenty は整数ではないため、 age エントリのフィルタは失敗します。 1 から 120 の範囲外の値の場合も、同じように失敗します。

<?php
$filters = [
    'email' => FILTER_VALIDATE_EMAIL,
    'age'   => [
        'filter'  => FILTER_VALIDATE_INT,
        'options' => ['min_range' => 1, 'max_range' => 120],
    ],
    'url'   => FILTER_VALIDATE_URL,
];

$result = filter_input_array(INPUT_GET, $filters);

var_dump($result);
?>

上の例の出力は、たとえば以下のようになります。

array(3) {
  ["email"]=>
  string(16) "user@example.com"
  ["age"]=>
  bool(false)
  ["url"]=>
  string(19) "https://example.com"
}

例2 filter_input_array() で POST データをフィルタリングする

この例では、 username=<script>alert</script> と comment=Hello World というフィールドを持つ POST リクエストを想定しています。 missing フィールドは送信されていませんが、 add_empty のデフォルトは true なので、結果には null として含まれます。

<?php
$filters = [
    'username' => FILTER_SANITIZE_SPECIAL_CHARS,
    'comment'  => FILTER_SANITIZE_SPECIAL_CHARS,
    'missing'  => FILTER_VALIDATE_INT,
];

$result = filter_input_array(INPUT_POST, $filters);

var_dump($result);
?>

上の例の出力は、たとえば以下のようになります。

array(3) {
  ["username"]=>
  string(38) "&#60;script&#62;alert&#60;/script&#62;"
  ["comment"]=>
  string(11) "Hello World"
  ["missing"]=>
  NULL
}

例3 値が入っていない入力の種類を指定する

この例では GET リクエストを想定しています。リクエストに POST フィールドが含まれていないため、 INPUT_POST で指定された入力配列には値が入っておらず、配列の代わりに null が返されます。これはどの入力の種類にも当てはまります。クエリ文字列のないリクエストでは、 INPUT_GET を指定した場合も null が返されます。

<?php
var_dump(filter_input_array(INPUT_POST, ['a' => FILTER_VALIDATE_INT]));
?>

上の例の出力は、たとえば以下のようになります。

NULL

注意

注意:
INPUT_SERVER 配列には、キー REQUEST_TIME が存在しません。あとで $_SERVER に追加されるからです。

参考

filter_input() - 指定した名前の変数を外部から受け取り、オプションでそれをフィルタリングする
filter_var() - 指定したフィルタでデータをフィルタリングする
filter_var_array() - 複数の変数を受け取り、オプションでそれらをフィルタリングする
検証フィルタ FILTER_VALIDATE_*
除去フィルタ FILTER_SANITIZE_*