filter_var_array

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

filter_var_array — 複数の変数を受け取り、オプションでそれらをフィルタリングする

説明

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

検証フィルタ FILTER_VALIDATE_* や、除去フィルタ FILTER_SANITIZE_*、またはカスタムフィルタを使って連想配列をフィルタリングします。

パラメータ

array

フィルタリングするデータを保持している連想配列

options

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

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

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

add_empty

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

戻り値

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

失敗した場合、false を返します。

入力配列に欠けているエントリは、 add_empty が true の場合は返される配列に null として追加され、 false の場合は一切含まれません。

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

例

例1 filter_var_array() の例

FILTER_REQUIRE_ARRAY または FILTER_FORCE_ARRAY を使わない限り、各エントリはスカラーとしてフィルタリングされます。そのため、以下の testscalar に指定している FILTER_REQUIRE_SCALAR フラグは、このデフォルトの動作を明示しているだけです。

<?php

$data = [
    'product_id' => 'libgd<script>',
    'component'  => '10',
    'versions'   => '2.0.33',
    'testscalar' => ['2', '23', '10', '12'],
    'testarray'  => '2',
];

$filters = [
    'product_id'   => FILTER_SANITIZE_ENCODED,
    'component'    => [
        'filter'   => FILTER_VALIDATE_INT,
        'flags'    => FILTER_FORCE_ARRAY,
        'options'  => [
            'min_range' => 1,
            'max_range' => 10,
        ],
    ],
    'versions'     => [
        'filter' => FILTER_SANITIZE_ENCODED
    ],
    'testscalar'   => [
        'filter' => FILTER_VALIDATE_INT,
        'flags'  => FILTER_REQUIRE_SCALAR,
    ],
    'testarray'    => [
        'filter' => FILTER_VALIDATE_INT,
        'flags'  => FILTER_FORCE_ARRAY,
    ],
    'doesnotexist' => FILTER_VALIDATE_INT,
];

var_dump(filter_var_array($data, $filters));

?>

上の例の出力は以下となります。

array(6) {
  ["product_id"]=>
  string(17) "libgd%3Cscript%3E"
  ["component"]=>
  array(1) {
    [0]=>
    int(10)
  }
  ["versions"]=>
  string(6) "2.0.33"
  ["testscalar"]=>
  bool(false)
  ["testarray"]=>
  array(1) {
    [0]=>
    int(2)
  }
  ["doesnotexist"]=>
  NULL
}

例2 ひとつのフィルタをすべての値に適用する

options が整数の場合は、配列のすべてのエントリに同じフィルタが適用されます。

<?php
$data = [
    'name'  => '<b>John</b>',
    'email' => 'john@example<script>.com',
    'bio'   => 'Developer & writer',
];

var_dump(filter_var_array($data, FILTER_SANITIZE_SPECIAL_CHARS));
?>

上の例の出力は以下となります。

array(3) {
  ["name"]=>
  string(27) "&#60;b&#62;John&#60;/b&#62;"
  ["email"]=>
  string(32) "john@example&#60;script&#62;.com"
  ["bio"]=>
  string(22) "Developer &#38; writer"
}

例3 FILTER_CALLBACK の使用例

<?php
$data = [
    'name'  => '  John Doe  ',
    'city'  => '  New York  ',
];

$options = [
    'name' => [
        'filter'  => FILTER_CALLBACK,
        'options' => 'trim',
    ],
    'city' => [
        'filter'  => FILTER_CALLBACK,
        'options' => function ($value) {
            return strtoupper(trim($value));
        },
    ],
];

var_dump(filter_var_array($data, $options));
?>

上の例の出力は以下となります。

array(2) {
  ["name"]=>
  string(8) "John Doe"
  ["city"]=>
  string(8) "NEW YORK"
}

参考

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