[edit] Last updated: Mon, 01 Nov 2010

XLI. フィルタ関数

導入

この拡張モジュールは、ユーザ入力などのセキュアでないデータの検証およびフィルタリングを行います。

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。このモジュールは自己責任で使用してください。

現在存在するのは、以下のフィルタです。各定数の振る舞いについての説明はフィルタ定数の節を参照ください。

表 1. 存在するフィルタ

ID	名前	オプション	フラグ	説明
`FILTER_VALIDATE_INT`	"int"	`min_range`, `max_range`	`FILTER_FLAG_ALLOW_OCTAL`, `FILTER_FLAG_ALLOW_HEX`	値が整数であるかどうか、オプションで指定した範囲内にあるかどうかを検証します。
`FILTER_VALIDATE_BOOLEAN`	"boolean"			"1"、"true"、"on" および "yes" の場合に `TRUE`、 "0"、"false"、"off"、"no" および "" の場合に `FALSE`、そしてそれ以外の場合に `NULL` を返します。
`FILTER_VALIDATE_FLOAT`	"float"			値が float であるかどうかを検証します。
`FILTER_VALIDATE_REGEXP`	"validate_regexp"	`regexp`		値が、Perl 互換の正規表現 `regexp` に一致するかどうかを検証します。
`FILTER_VALIDATE_URL`	"validate_url"		`FILTER_FLAG_SCHEME_REQUIRED`, `FILTER_FLAG_HOST_REQUIRED`, `FILTER_FLAG_PATH_REQUIRED`, `FILTER_FLAG_QUERY_REQUIRED`	値が URL 形式であるかどうか、オプションで指定したコンポーネントが含まれているかどうかを検証します。
`FILTER_VALIDATE_EMAIL`	"validate_email"			値が e-mail 形式であるかどうかを検証します。
`FILTER_VALIDATE_IP`	"validate_ip"		`FILTER_FLAG_IPV4`, `FILTER_FLAG_IPV6`, `FILTER_FLAG_NO_PRIV_RANGE`, `FILTER_FLAG_NO_RES_RANGE`	値が IP アドレスであるかどうかを検証します。オプションで IPv4 あるいは IPv6 のみの指定、プライベートアドレスや予約済みアドレスではないことの指定もできます。
`FILTER_SANITIZE_STRING`	"string"		`FILTER_FLAG_NO_ENCODE_QUOTES`, `FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_LOW`, `FILTER_FLAG_ENCODE_HIGH`, `FILTER_FLAG_ENCODE_AMP`	タグを取り除きます。オプションで、特殊文字を取り除いたりエンコードしたりします。
`FILTER_SANITIZE_STRIPPED`	"stripped"			"string" フィルタのエイリアス。
`FILTER_SANITIZE_ENCODED`	"encoded"		`FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_LOW`, `FILTER_FLAG_ENCODE_HIGH`	文字列を URL エンコードします。オプションで、特殊文字を取り除いたりエンコードしたりします。
`FILTER_SANITIZE_SPECIAL_CHARS`	"special_chars"		`FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_HIGH`	`'"<>&` および ASCII 値が 32 未満の文字を HTML エスケープします。オプションで、特殊文字を取り除いたりエンコードしたりします。
`FILTER_UNSAFE_RAW`	"unsafe_raw"		`FILTER_FLAG_STRIP_LOW`, `FILTER_FLAG_STRIP_HIGH`, `FILTER_FLAG_ENCODE_LOW`, `FILTER_FLAG_ENCODE_HIGH`, `FILTER_FLAG_ENCODE_AMP`	何もせず、オプションで特殊文字を取り除いたりエンコードしたりします。
`FILTER_SANITIZE_EMAIL`	"email"			英字、数字および !#$%&'*+-/=?^_`{\|}~@.[] 以外のすべての文字を取り除きます。
`FILTER_SANITIZE_URL`	"url"			英字、数字および $-_.+!*'(),{}\|\\^~[]`<>#%";/?:@&= 以外のすべての文字を取り除きます。
`FILTER_SANITIZE_NUMBER_INT`	"number_int"			数字および `+-` 以外のすべての文字を取り除きます。
`FILTER_SANITIZE_NUMBER_FLOAT`	"number_float"		`FILTER_FLAG_ALLOW_FRACTION`, `FILTER_FLAG_ALLOW_THOUSAND`, `FILTER_FLAG_ALLOW_SCIENTIFIC`	数字、`+-` およびオプションで `.,eE` 以外のすべての文字を取り除きます。
`FILTER_SANITIZE_MAGIC_QUOTES`	"magic_quotes"			addslashes() を適用します。
`FILTER_CALLBACK`	"callback"		callback 関数あるいはメソッド	ユーザ定義の関数をコールしてデータをフィルタリングします。

要件

外部ライブラリを必要としません。

インストール手順

簡単なインストールメモ。コンソールで、ただ単に

$ pecl install filter

とタイプします。

実行時設定

php.ini の設定により動作が変化します。

表 2. フィルタ設定オプション

名前	デフォルト	変更の可否	変更履歴
filter.default	unsafe_raw	PHP_INI_PERDIR
filter.default_flags		PHP_INI_PERDIR

PHP_INI_* 定数の詳細および定義については付録G を参照してください。

以下に設定ディレクティブに関する簡単な説明を示します。

filter.default string

このフィルタで $_GET, $_POST, $_COOKIE および $_REQUEST のすべてのデータをフィルタリングします。もとのデータへは filter_input() でアクセスが可能です。

デフォルトで使用するフィルタの名前を指定することができます。既存のフィルタの一覧を参照し、フィルタ名を指定してください。

filter.default_flags integer

デフォルトのフラグ。

リソース型

リソース型は定義されていません。

定義済み定数

以下の定数が定義されています。この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、実行時に動的にロードされている場合のみ使用可能です。

INPUT_POST (integer): POST 変数。
INPUT_GET (integer): GET 変数。
INPUT_COOKIE (integer): COOKIE 変数。
INPUT_ENV (integer): ENV 変数。
INPUT_SERVER (integer): SERVER 変数。
INPUT_SESSION (integer): SESSION 変数 (まだ実装されていません)。
INPUT_REQUEST (integer): REQUEST 変数 (まだ実装されていません)。
FILTER_FLAG_NONE (integer): フィルタしない。
FILTER_REQUIRE_SCALAR (integer): 入力値としてスカラーを要求するために使用するフラグ。
FILTER_REQUIRE_ARRAY (integer): 入力として配列を要求します。
FILTER_FORCE_ARRAY (integer): 常に配列として返します。
FILTER_NULL_ON_FAILURE (integer): 失敗した場合に FALSE ではなく NULL を使用します。
FILTER_VALIDATE_INT (integer): "int" フィルタの ID。
FILTER_VALIDATE_BOOLEAN (integer): "boolean" フィルタの ID。
FILTER_VALIDATE_FLOAT (integer): "float" フィルタの ID。
FILTER_VALIDATE_REGEXP (integer): "validate_regexp" フィルタの ID。
FILTER_VALIDATE_URL (integer): "validate_url" フィルタの ID。
FILTER_VALIDATE_EMAIL (integer): "validate_email" フィルタの ID。
FILTER_VALIDATE_IP (integer): "validate_ip" フィルタの ID。
FILTER_DEFAULT (integer): デフォルト ("string") フィルタの ID。
FILTER_UNSAFE_RAW (integer): "unsafe_raw" フィルタの ID。
FILTER_SANITIZE_STRING (integer): "string" フィルタの ID。
FILTER_SANITIZE_STRIPPED (integer): "stripped" フィルタの ID。
FILTER_SANITIZE_ENCODED (integer): "encoded" フィルタの ID。
FILTER_SANITIZE_SPECIAL_CHARS (integer): "special_chars" フィルタの ID。
FILTER_SANITIZE_EMAIL (integer): "email" フィルタの ID。
FILTER_SANITIZE_URL (integer): "url" フィルタの ID。
FILTER_SANITIZE_NUMBER_INT (integer): "number_int" フィルタの ID。
FILTER_SANITIZE_NUMBER_FLOAT (integer): "number_float" フィルタの ID。
FILTER_SANITIZE_MAGIC_QUOTES (integer): "magic_quotes" フィルタの ID。
FILTER_CALLBACK (integer): "callback" フィルタの ID。
FILTER_FLAG_ALLOW_OCTAL (integer): "int" フィルタで 8 進表記 (0[0-7]+) を許可します。
FILTER_FLAG_ALLOW_HEX (integer): "int" フィルタで 16 進表記 (0x[0-9a-fA-F]+) を許可します。
FILTER_FLAG_STRIP_LOW (integer): ASCII 値が 32 未満の文字を取り除きます。
FILTER_FLAG_STRIP_HIGH (integer): ASCII 値が 127 より大きい文字を取り除きます。
FILTER_FLAG_ENCODE_LOW (integer): ASCII 値が 32 未満の文字をエンコードします。
FILTER_FLAG_ENCODE_HIGH (integer): ASCII 値が 127 より大きい文字をエンコードします。
FILTER_FLAG_ENCODE_AMP (integer): & をエンコードします。
FILTER_FLAG_NO_ENCODE_QUOTES (integer): ' および " をエンコードしません。
FILTER_FLAG_EMPTY_STRING_NULL (integer): (現在は使用されていません)
FILTER_FLAG_ALLOW_FRACTION (integer): "number_float" フィルタで小数を許可します。
FILTER_FLAG_ALLOW_THOUSAND (integer): "number_float" フィルタで桁区切り文字 (,) を許可します。
FILTER_FLAG_ALLOW_SCIENTIFIC (integer): "number_float" フィルタで科学記法 (e, E) を許可します。
FILTER_FLAG_SCHEME_REQUIRED (integer): "validate_url" フィルタでスキームを必須とします。
FILTER_FLAG_HOST_REQUIRED (integer): "validate_url" フィルタでホスト名を必須とします。
FILTER_FLAG_PATH_REQUIRED (integer): "validate_url" フィルタでパスを必須とします。
FILTER_FLAG_QUERY_REQUIRED (integer): "validate_url" フィルタでクエリ文字列を必須とします。
FILTER_FLAG_IPV4 (integer): "validate_ip" フィルタで IPv4 アドレスのみを許可します。
FILTER_FLAG_IPV6 (integer): "validate_ip" フィルタで IPv6 アドレスのみを許可します。
FILTER_FLAG_NO_RES_RANGE (integer): "validate_ip" フィルタで予約済みアドレスを拒否します。
FILTER_FLAG_NO_PRIV_RANGE (integer): "validate_ip" フィルタでプライベートアドレスを拒否します。

目次
filter_has_var -- 指定した型の変数が存在するかどうかを調べる
filter_id -- フィルタの名前からフィルタ ID を返す
filter_input_array -- PHP の外部から複数の変数を受け取り、オプションでそれらをフィルタリングする
filter_input -- PHP の外部から変数を受け取り、オプションでそれをフィルタリングする
filter_list -- サポートされるフィルタの一覧を返す
filter_var_array -- 複数の変数を受け取り、オプションでそれらをフィルタリングする
filter_var -- 指定したフィルタでデータをフィルタリングする

filter_has_var

unlink

[edit] Last updated: Mon, 01 Nov 2010

add a note User Contributed Notes フィルタ関数

Anonymous 24-Dec-2008 09:08


--quoted from filter.txt in the source code



* As the input filter acts on input data before the magic quotes function

  mangles data, all access through the filter() function will not have any

  quotes or slashes added - it will be the pure data as send by the browser.

Jovan Suervo 26-Nov-2007 01:35


It seems that all FILTER_VALIDATE_URL is doing is calling parse_url(), which makes it effectively useless since parse_url() only fails on really malformed urls.



<?php

$url = 'http://...';



var_dump(filter_var($url, FILTER_VALIDATE_URL));

?>



Will display: string(10) "http://..."



None of the flags help either, so you're better off with regular expressions to validate a url.

fumble1 at web dot de 12-Aug-2007 10:54


I recommend you to use the FILTER_REQUIRE_SCALAR (or FILTER_REQUIRE_ARRAY) flags, since you can use array-brackets both to access string offsets and array-element -- however, not only this can lead to unexpected behaviour. Look at this example:



<?php

$image = basename(filter_input(INPUT_GET, 'src', FILTER_UNSAFE_RAW, FILTER_FLAG_STRIP_LOW));

// further checks

?>



/script.php?src[0]=foobar will cause a warning. :-(

Hence my recommendation:



<?php

$image = basename(filter_input(INPUT_GET, 'src', FILTER_UNSAFE_RAW, FILTER_REQUIRE_SCALAR | FILTER_FLAG_STRIP_LOW));

// further checks

?>

Richard Davey rich at corephp dot co dot uk 13-Jun-2007 11:15


There is an undocumented filter flag for FILTER_VALIDATE_BOOLEAN. The documentation implies that it will return NULL if the value doesn't match the allowed true/false values. However this doesn't happen unless you give it the FILTER_NULL_ON_FAILURE flag like this:



<?php

$value = 'car';

$result = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);

?>



In the above $result will equal NULL. Without the extra flag it would equal FALSE, which isn't usually a desired result for this specific filter.

ckroll at rightmedia dot com 08-May-2007 08:02


Beware, the FILTER_SANITIZE_STRING flag functions much like strip_tags, so < will get filtered from input regardless of it's actually part of a tag.  We were getting unexepected results with a graphic library we wrote when trying to print < on a dynamic button.  The url came in something like ?string=%3C (<) but after filter ran it was empty.  To get around this, you could use FILTER_UNSAFE_RAW on that one param.

user 02-Feb-2007 12:15


Below is some code using filter API to restrict access to LAN by IPv4 private address range.



These notes may save someone else a little time:



filter_input_array() is useless for running multiple filters on the same key.

No way to chain or negate filters.



<?php



/* Merciful comment! */

function FILTER_NEGATE_HACK($_){ return (bool)!$_; }



function client_is_private_ipv4(){

  return (filter_input(INPUT_SERVER, 'REMOTE_ADDR', FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) && 

            FILTER_NEGATE_HACK(filter_input(INPUT_SERVER, 'REMOTE_ADDR', FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE));

}



if (! client_is_private_ipv4()) 

  exit('This application is restricted to local network users');



?>

vojtech at x dot cz 21-Dec-2006 06:38


Also notice that filter functions are using only the original variable values passed to the script even if you change the value in super global variable ($_GET, $_POST, ...) later in the script.



<?php

echo filter_input(INPUT_GET, 'var'); // print 'something'

echo $_GET['var']; // print 'something'

$_GET['var'] = 'changed';

echo filter_input(INPUT_GET, 'var'); // print 'something'

echo $_GET['var']; // print 'changed'

?>



In fact, external data are duplicated in SAPI before the script is processed and filter functions don't use super globals anymore (as explained in Filter tutorial bellow, section 'How does it work?').

vojtech at x dot cz 21-Dec-2006 05:13


Just to note that "server and env support may not work in all sapi, for filter 0.11.0 or php 5.2.0" as mentioned in Filter tutorial bellow.



The workaround is obvious:

Instead of 

<?php

$var = filter_input(INPUT_SERVER, 'SERVER_NAME', FILTER_DEFAULT);

?>

use

<?php

$var = filter_var(isset($_SERVER['SERVER_NAME']) ? $_SERVER['SERVER_NAME'] : NULL, FILTER_DEFAULT);

?>

add a note