Caution: You are browsing the legacy symfony 1.x part of this website.

付録 B - バリデータ

1.4
Symfony version
1.2
Language

はじめに

symfony フォームフレームワークにはたくさんの便利なバリデータが搭載されています。これらのバリデータは大半のプロジェクトの共通ニーズをカバーします。この章では symfony に搭載されているデフォルトのフォームバリデータを説明します。sfPropelPluginsfDoctrinePlugin プラグインにもバリデータが含まれています。これらのプラグインは symfony のコアチームによってサポートされており、とても便利なバリデータが含まれています。

tip

symfony MVC フレームワークを使わない場合でも、プロジェクトのどこかの validator/ ディレクトリに設置することで、sfFormExtraPluginsfPropelPluginsfDoctrinePlugin プラグインに含まれているバリデータを使うことができます。

それぞれのバリデータのくわしい内容に飛び込む前に、バリデータの共通機能を見てみましょう。

sfValidatorBase 基底クラス

symfonyのすべてのバリデータは sfValidator 基底クラスを継承します。 このクラスはすべてのバリデータで利用可能なデフォルト機能を提供します。

バリデータは2つの目標: 汚染されている値をクリーンにすることとバリデーションを実行することです。

バリデータを作るとき、オプションとエラーメッセージをオプションの引数に渡すことができます。

$v = new sfValidatorString(
  array('required' => true),
  array('required' => 'This value is required.')
);

setOptions()setMessages() メソッドを呼び出すことでもオプションとメッセージを設定できます。

$v = new sfValidatorString();
$v->setOptions(array('required' => true));
$v->setMessages(array('required' => 'This value is required.'));

setOption()setMessage() メソッドを呼び出すことで、個別のオプションもしくはエラーメッセージを設定できます。

$v = new sfValidatorString();
$v->setOption('required', true);
$v->setMessage('required', 'This value is required.');

clean() メソッドを呼び出すことで汚染されている値のバリデーションを行うことができます。

$cleaned = $v->clean('name', 'value', array('class' => 'foo'));

clean() メソッドは汚染されている値を引数にとり、クリーンな値を返します。 バリデーションエラーが起きるとき、sfValidatorError が投げられます。

note

バリデータはステートレスなので、単独のバリデータインスタンスは望む数だけ入力値のバリデーションを行うことができることを意味します。

sfValidatorBase によって定義されているデフォルトのオプションは次のとおりです。

オプション エラー 説明
required required 値が必須の場合は true、そうでなければ false (デフォルトは true)
trim n/a 値をトリミングしなければならない場合は true、そうでなければ false (デフォルトは false)
empty_value n/a 値が必須ではないときに返される空の値

sfValidatorBase によって定義されているデフォルトのエラーメッセージは次のとおりです。

エラー 説明
required 汚染されている値が空で必須であるときに使われるエラーメッセージ (デフォルトは Required.)。
invalid エラーが起きるときに一般的なエラーメッセージ (デフォルトは Invalid.)。

setDefaultMessage() メソッドを呼び出すことで requiredinvalid エラーメッセージに使われるデフォルトの文字列を変更できます。

public function setup()
{
  sfValidatorBase::setDefaultMessage('required', 'This value is required.');
  sfValidatorBase::setDefaultMessage('invalid', 'This value is invalid.');
  parent::setup();
}

エラーメッセージではプレースホルダを使うことができます。プレースホルダは % で囲まれた文字列です。実行時にプレースホルダは置き換えられます。すべてのエラーメッセージは %value% プレースホルダで汚染されている値にアクセスする権限をもっています。それぞれのエラーメッセージは特定のプレースホルダも定義できます。

note

デフォルトの %value% プレースホルダはつねに利用可能ではないので、 次の節では説明しません。

バリデータのなかには汚染されている値によって使われる文字集合を知る必要があるものがあります。デフォルトの文字集合は UTF-8 ですが、setCharset() メソッドを呼び出して変更することもできます。

sfValidatorBase::setCharset('ISO-8859-1');

note

symfony MVC フレームワークで symfony のバリデータを使う場合、settings.yml の charset にしたがって文字集合は自動的に設定されます。

バリデータスキーマ

バリデータスキーマは1つもしくはほかの複数のバリデータのラッパーバリデータです。

エラーが起きるとき、バリデータスキーマは例外オブジェクトの sfValidatorErrorSchema を投げます。

次の節では、バリデータは複数のカテゴリにわけて説明します。

バリデータ

シンプルなバリデータ

sfValidatorString

スキーマバリデータ: No

sfValidatorString バリデータは文字列のバリデーションを行い、汚染されている値を文字列に変換します。

オプション エラー 説明
max_length max_length 文字列の最長の長さ
min_length min_length 文字列の最短の長さ
エラー プレースホルダ デフォルト値
max_length max_length "%value%" is too long (%max_length% characters max).
min_length min_length "%value%" is too short (%min_length% characters min).

caution

このバリデータを正しく動作させるには PHP の mb_string エクステンションをインストールしていなければなりません。インストールされていれば、文字列の長さは mb_strlen() 関数で算出されます。インストールされていなければ strlen() 関数が使われますが、文字列の中に ASCII 文字ではないものがある場合、本当の文字列の長さは返されません。

sfValidatorRegex

スキーマバリデータ: No

sfValidatorRegex バリデータは正規表現に対して文字列のバリデーションを行います。

オプション エラー 説明
pattern invalid PCRE の正規表現もしくは、正規表現を返す sfCallable のインスタンス
must_match invalid false がセットされている場合、正規表現はパスするバリデータにマッチしません。

sfValidatorEmail

スキーマバリデータ: No

sfValidatorEmail バリデータはメールアドレスのバリデーションを行います。このバリデータは sfValidatorRegex を継承します。

sfValidatorUrl

スキーマバリデータ: No

sfValidatorUrl バリデータは HTTP と FTP の URL のバリデーションを行います。このバリデータは sfValidatorRegex を継承します。

オプション エラー 説明
protocols invalid 許可されるプロトコル。デフォルトは array('http', 'https', 'ftp', 'ftps')

sfValidatorInteger

スキーマバリデータ: No

sfValidatorIntegerバリデータは整数のバリデーションを行い、汚染されている値を整数に変換します。

オプション エラー 説明
max max 受け入れられる整数の最大値
min min 受け入れられる整数の最小値
エラー プレースホルダ デフォルト値
max max "%value%" must be less than %max%.
min min "%value%" must be greater than %min%.

デフォルトの invalid エラーメッセージは "%value%" is not an integer. です。

sfValidatorNumber

スキーマバリデータ: No

sfValidatorNumber バリデータは数値のバリデーションを行い、汚染されている値を浮動小数に変換します (PHP が floatval() 関数で理解できる文字列)。

オプション エラー 説明
max max 受け入れられる浮動小数の最大値
min min 受け入れられる浮動小数の最小値
エラー プレースホルダ デフォルト値
max max "%value%" must be less than %max%.
min min "%value%" must be greater than %min%.

デフォルトの invalid エラーメッセージは "%value%" is not a number. です。

sfValidatorBoolean

スキーマバリデータ: No

sfValidatorBoolean バリデータはブール値のバリデーションを行い、true もしくは false のどちらかを返します。

オプション エラー 説明
true_values n/a true の値のリスト (デフォルト: true, t, yes, y, on, 1)
false_values n/a false の値のリスト (デフォルト: false, f, no, n, off, 0)

sfValidatorChoice

スキーマバリデータ: No

sfValidatorChoice バリデータは汚染されている値が期待される値のリストの範囲に収まっているかどうかのバリデーションを行います。

オプション エラー 説明
choices n/a 期待される値の配列 (必須)
multiple n/a select タグが複数の値を許可しなければならない場合は true
min n/a 必須の値の最小値 (multiple の値が true である場合)
max n/a 必須の値の最大値 (multiple の値が true である場合)

note

比較は汚染されている値が文字列にキャストされた後に行われます。

sfValidatorPass

スキーマバリデータ: No

sfValidatorPass バリデータは何もしないバリデータで汚染されている値をそのまま返します。

sfValidatorCallback

スキーマバリデータ: No

sfValidatorCallback バリデータは実際のバリデーション作業を PHP コールバックにゆだねます。

汚染されている値とコールバックの引数の配列は arguments オプションを通じて現在のバリデータインスタンスに渡されます。

function constant_validator_callback($validator, $value, $arguments)
{
  if ($value != $arguments['constant'])
  {
    throw new sfValidatorError($validator, 'invalid');
  }
 
  return $value;
}
 
$v = new sfValidatorCallback(array(
  'callback'  => 'constant_validator_callback',
  'arguments' => array('constant' => 'foo'),
));
オプション エラー 説明
callback n/a 有効な PHP コールバック (必須)
arguments n/a コールバックに渡される引数の配列

日付バリデータ

sfValidatorDate

スキーマバリデータ: No

sfValidatorDate は日付と時刻の組のバリデーションを行います (日付と時刻の組は with_time オプションに値をセットすることでサポートされます)。 日付フォーマットのバリデーションを行うこととは別に、妥当な日付の最大最小値を強制できます。

バリデータはさまざまな入力タイプを受け入れます。

  • 次のキーで構成される配列: yearmonthdayhourminutesecond
  • 提供されるのであれば date_format 正規表現にマッチする文字列 (たとえば ~(?P<day>\d{2})/(?P<month>\d{2})/(?P<year>\d{4})~)
  • PHP の strtotime() 関数によって解析できる文字列
  • タイムスタンプをあらわす整数

date_output もしくは datetime_output フォーマットを適用することで汚染されている値は日付に変換されます。

オプション エラー 説明
date_format bad_format 日付がマッチしなければならない正規表現。正規表現は (?P<year>) のような名前つきサブパターンを使わなければならないことにご注意ください。
with_time n/a バリデータが時刻を返さなければならないのであれば true、そうでなければ false
date_output n/a 日付を返す際に適用されるフォーマット (デフォルトは Y-m-d)
datetime_output n/a 日付と時刻の組を返す際に適用されるフォーマット (デフォルトは Y-m-d H:i:s)
date_format_error n/a bad_format エラーに対してエラーを表示する際に適用されるフォーマット (use date_format if not provided)
max max 許容される日付の最大値 (タイムスタンプ)
min min 許容される日付の最小値 (タイムスタンプ)
date_format_range_error n/a 最大/最小に対してエラーを表示する際に適用される日付のフォーマット (デフォルトは d/m/Y H:i:s)

note

date_outputdatetime_output オプションは PHP の date() 関数が理解できる任意のフォーマットを使うことができます

エラー プレースホルダ デフォルト値
bad_format date_format "%value%" does not match the date format (%date_format%).
min min The date must be after %min%.
max max The date must be before %max%.

sfValidatorTime

スキーマバリデータ: No

sfValidatorTime は時刻のバリデーションを行います。

バリデータはさまざまな入力のタイプを受け入れます。

  • 次のキーで構成される配列: hourminute、とsecond
  • 提供される場合 time_format 正規表現にマッチする文字列
  • PHP の strtotime() 関数によってパース可能な文字列
  • タイムスタンプをあらわす整数

datetime_output のフォーマットを適用することで汚染されている値は日付に変換されます。

オプション エラー 説明
time_format bad_format 日付がマッチしなければならない正規表現
time_output n/a 時刻を返す際に使われるフォーマット (デフォルトは H:i:s)
time_format_error n/a bad_format エラーに対してエラーを表示する際に適用される日付のフォーマット (提供されなければ date_format が適用されます)

note

time_output オプションは PHP の date() 関数が理解する任意のフォーマットを使うことができます。

エラー プレースホルダ デフォルト値
bad_format time_format "%value%" does not match the time format (%time_format%).

sfValidatorDateTime

スキーマバリデータ: No

sfValidatorDateTime は時刻が datetime 型であるかのバリデーションを行います。

これは次のコードのショートカットです。

$v = new sfValidatorDate(array('with_time' => true));

sfValidatorDateRange

スキーマバリデータ: No

sfValidatorDateTime は日付の範囲のバリデーションを行います。

オプション エラー 説明
from_date invalid from date バリデータ (必須)
to_date invalid to date バリデータ (必須)

from_dateto_date バリデータは sfValidatorDate クラスのインスタンスでなければなりません。

invalid エラーメッセージは "%value%" does not match the time format (%time_format%). です。

ファイルバリデータ

sfValidatorFile

スキーマバリデータ: No

sfValidatorFile バリデータはアップロードされたファイルのバリデーションを行います。

バリデータはアップロードされたファイルを sfValidatedFile クラスのインスタンス、もしくは設定されているのであれば、validated_file_class オプションのインスタンスに変換します。

オプション エラー 説明
max_size max_size 最大のファイルサイズ
mime_types mime_types 許可された MIME Type の配列もしくはカテゴリ (利用可能なカテゴリ: web_images)
mime_type_guessers n/a MIME Type を推測する PHP callable の配列 (MIME Type もしくは null を返さなければならない)
mime_categories n/a MIME Type カテゴリの配列 (デフォルトで web_images が定義される)
path n/a ファイルを保存するパス - sfValidatedFile クラスによって使用される (オプション)
validated_file_class n/a クリーンにされたアップロードファイルを管理するクラスの名前 (オプション)

web_images カテゴリは 次の MIME Type を含みます。

  • image/jpeg
  • image/pjpeg
  • image/png
  • image/x-png
  • image/gif

mime_types オプションが設定されている場合、バリデータはアップロードされたファイルの mime-type をテストする方法が必要です。バリデータは3つの方法を搭載しています。

  • guessFromFileinfo: finfo_open() 関数を使う (PECL の Fileinfo エクステンションから)
  • guessFromMimeContentType: mime_content_type() 関数を使う (非推奨)
  • guessFromFileBinary: ファイルバイナリを使う (Unix 系システムでのみ動作する)
エラー プレースホルダ デフォルト値
max_size %size%, %max_size% File is too large (maximum is %max_size% bytes).
mime_types %mime_types%, %mime_type% Invalid mime type (%mime_type%).
partial The uploaded file was only partially uploaded.
no_tmp_dir Missing a temporary folder.
cant_write Failed to write file to disk.
extension File upload stopped by extension.

バリデータはPHPエラーを次のようにマッピングします。

  • UPLOAD_ERR_INI_SIZE: max_size
  • UPLOAD_ERR_FORM_SIZE: max_size
  • UPLOAD_ERR_PARTIAL: partial
  • UPLOAD_ERR_NO_TMP_DIR: no_tmp_dir
  • UPLOAD_ERR_CANT_WRITE: cant_write
  • UPLOAD_ERR_EXTENSION: extension

論理バリデータ

sfValidatorAnd

スキーマバリデータ: No

バリデータのリストを渡す場合、sfValidatorAnd バリデータは汚染されている値のバリデーションを行います。

sfValidatorAnd コンストラクタはバリデータのリストを第1引数にとります。

$v = new sfValidatorAnd(
  array(
    new sfValidatorString(array('max_length' => 255)),
    new sfValidatorEmail(),
  ),
  array('halt_on_error' => true),
  array('invalid' => 'The input value must be an email with less than 255 characters.')
);

デフォルトでは、バリデータはすべての埋め込みバリデータからのエラーメッセージの配列を投げます。 invalid エラーメッセージが空ではない文字列に設定されている場合、次のように単独のエラーメッセージを投げることもできます。

オプション エラー 説明
halt_on_error n/a 最初のエラーで停止するかどうか (デフォルトは false)

halt_on_error オプションに true がセットされている場合、バリデータの順序は重要です。

バリデータの埋め込みリストは getValidators()addValidator() メソッドを使って管理することができます。

sfValidatorOr

スキーマバリデータ: No

リストの少なくとも1つのバリデータから汚染されている値が通る場合、sfValidatorOr バリデータはその汚染されている値のバリデーションを行います。

sfValidatorOr コンストラクタはバリデータのリストを第1引数にとります。

$v = new sfValidatorOr(
  array(
    new sfValidatorRegex(array('pattern' => '/\.com$/')),
    new sfValidatorEmail(),
  ),
  array(),
  array('invalid' => 'The input value a .com domain or a valid email address.')
);

デフォルトでは、すべての埋め込みバリデータからのエラーメッセージの配列が投げられます。 invalid エラーメッセージが空ではない文字列に設定されている場合、上述の例のようにこのバリデータは単独のエラーメッセージを投げることもできます。

バリデータの埋め込みリストは getValidators()addValidator() メソッドを使って管理できます。

sfValidatorSchema

スキーマバリデータ: Yes

sfValidatorSchema はいくつかのフィールドで構成されるバリデータをあらわします。フィールドは名前がつけられているシンプルなバリデータです。

$v = new sfValidatorSchema(array(
  'name'    => new sfValidatorString(),
  'country' => new sfValidatorI18nChoiceCountry(),
));

note

フォームは sfValidatorSchema クラスのバリデータスキーマで定義されます。

このバリデータは配列を入力値としてのみ受け入れ、値が当てはまらない場合 InvalidArgumentException を投げます。

バリデータはプレバリデータとポストバリデータを持つことができます。 プレバリデータはほかのすべてのバリデータの前に実行され、 ポストバリデータはほかのすべてのバリデータの後でクリーンナップされた値で実行されます。

プレバリデータとポストバリデータはすべての値を受け入れるバリデータスキーマそのものです。 これらは setPreValidator()setPostValidator() メソッドで設定できます。

$v->setPostValidator(
  new sfValidatorSchemaCompare('password', '==', 'password_again')
);
オプション エラー 説明
allow_extra_fields extra_fields falseの場合、追加フィールドが値の入力配列に渡される場合、バリデータはエラーを追加します (デフォルトは false)
filter_extra_fields n/a trueの場合、バリデータはクリーンになり、返される値の配列からの追加フィールドをフィルタリングします (デフォルトは true)
エラー プレースホルダ デフォルト値
extra_fields %field% Unexpected extra form field named "%field%".

埋め込みのバリデータにアクセスするために sfValidatorSchema を配列として使うことができます。

$vs = new sfValidatorSchema(array('name' => new sfValidatorString()));
 
$nameValidator = $vs['name'];
 
unset($vs['name']);

埋め込みのバリデータスキーマに配列記法でアクセスできます。

$vs['author']['first_name']->setMessage('invalid', 'The first name is invalid.');

sfValidatorSchemaCompare

スキーマバリデータ: Yes

sfValidatorSchemaCompare バリデータは汚染されている値の配列から複数の値を比較します。

$v = new sfValidatorSchemaCompare('password', '==', 'password_again');
オプション エラー 説明
left_field n/a 左側フィールドの名前
operator n/a 比較演算子
right_field n/a 右側フィールドの名前
throw_global_error n/a グローバルエラー (デフォルトは false) もしくは左側フィールドに結びつけられたエラーを投げるかどうか

利用可能な演算子の一覧は次のとおりです。

  • sfValidatorSchemaCompare::EQUAL もしくは ==
  • sfValidatorSchemaCompare::IDENTICAL もしくは ===
  • sfValidatorSchemaCompare::NOT_EQUAL もしくは !=
  • sfValidatorSchemaCompare::NOT_IDENTICAL もしくは !==
  • sfValidatorSchemaCompare::LESS_THAN もしくは <
  • sfValidatorSchemaCompare::LESS_THAN_EQUAL もしくは <=
  • sfValidatorSchemaCompare::GREATER_THAN もしくは >
  • sfValidatorSchemaCompare::GREATER_THAN_EQUAL もしくは >=

デフォルトでは、バリデータはグローバルエラーを投げます。 throw_global_errortrue がセットされている場合、左側フィールドのエラーが投げられます。

invalid エラーメッセージは次の値: %left_field%%right_field%%operator% を受け入れます。

sfValidatorSchemaFilter

スキーマバリデータ: Yes

sfValidatorSchemaFilter バリデータはスキーマではないバリデータをスキーマバリデータに変換します。 これはポストバリデータのコンテキストに役立ちます。

$v = new sfValidatorSchema();
$v->setPostValidator(
  new sfValidatorSchemaFilter('email', new sfValidatorEmail())
);

国際化バリデータ

sfValidatorI18nChoiceCountry

スキーマバリデータ: No

sfValidatorI18nChoiceCountry は汚染されている値が ISO 3166 の有効な国コードであるかどうかのバリデーションを行います。

オプション エラー 説明
countries invalid 国コードの配列 (ISO 3166)

sfValidatorI18nChoiceLanguage

スキーマバリデータ: No

sfValidatorI18nChoiceLanguage は汚染されている値が有効な言語コードであるかどうかのバリデーションを行います。

オプション エラー 説明
languages invalid 言語コードの配列

sfValidatorI18nChoiceTimezone

スキーマバリデータ: No

sfValidatorI18nChoiceTimezone は汚染されている値が有効なタイムゾーンであるかどうかのバリデーションを行います。

オプション エラー 説明
languages invalid 言語コードの配列

Propel バリデータ

sfValidatorPropelChoice

スキーマバリデータ: No

sfValidatorPropelChoice バリデータは汚染されている値が Propel モデルのレコードのリストの範囲にあるかどうかのバリデーションを行います。

criteria オプションを使うことでレコードのリストを制限できます。

汚染されている値はレコードのプライマリキーでなければなりません。これは column オプションを渡すことで変更できます。

オプション エラー 説明
model n/a モデルクラス (必須)
criteria n/a オブジェクトを読み取るときにしたがう基準
column n/a カラム名 (デフォルトは null でプライマリキーが使われることを意味する) - フィールド名のフォーマットでなければならない
connection n/a Propel のコネクション (デフォルトは null)
multiple n/a select タグが複数の選択肢を許可しなければならない場合は true

note

このバリデータは複合プライマリキーをもつモデルに対しては機能しません。

sfValidatorPropelUnique

スキーマバリデータ: Yes

sfValidatorPropelUnique バリデータは Propel モデルのカラムもしくはカラムのグループ (column オプション) の一意性のバリデーションを行います。

一意性が複数のカラムに及ぶ場合、throw_global_error オプションを設定することでグローバルエラーが投げられます。

オプション エラー 説明
model n/a モデルクラス (必須)
column n/a Propel フィールド名フォーマットのユニークカラム名 (必須)。複数のカラムに一意性があれば、フィールド名の配列を渡すことができます
field n/a カラム名以外で、フォームによって使われるフィールド名
primary_key n/a Propel のフィールド名のフォーマットでのプライマリキーのカラム名 (オプションとして、提供されなければイントロスペクトされます)。テーブルに複数のプライマリキーがある場合は配列を渡すこともできます
connection n/a Propel のコネクション (デフォルトは null)
throw_global_error n/a グローバルエラー (デフォルトは false) もしくはカラムオプションの配列に関連した最初のフィールドに結びつけられたエラーを投げるかどうか

Doctrine バリデータ

sfValidatorDoctrineChoice

スキーマバリデータ: No

sfValidatorDoctrineChoice バリデータは汚染されている値が Doctrine モデルのレコードのリストの範囲にあるかどうかのバリデーションを行います。

query オプションを使ってレコードのリストを制限できます。

汚染されている値はレコードのプライマリキーでなければなりません。これは column オプションを渡すことで変更できます。

オプション エラー 説明
model n/a モデルクラス(必須)
alias n/a クエリで使われるルートコンポーネントのエイリアス
query n/a オブジェクトが検索されるときに使われるクエリ
column n/a カラム名 (デフォルトは null でプライマリキーが使われることを意味します) - フィールド名のフォーマットでなければならない
connection n/a Doctrine のコネクション (デフォルトは null)

note

このバリデータは複合プライマリキーをもっているモデルに対しては機能しません。

sfValidatorDoctrineUnique

スキーマバリデータ: Yes

sfValidatorDoctrineUnique バリデータは Doctrine モデルに対する1つのカラムもしくはカラムのグループ (column オプション) の一意性のバリデーションを行います。

複数のカラムに一意性がある場合、throw_global_error オプションを設定することでグローバルエラーが投げられるようになります。

オプション エラー 説明
model n/a モデルクラス (必須)
column n/a Doctrine のフィールド名フォーマットのユニークカラムの名前 (必須)。複数のカラムに一意性がある場合、フィールド名の配列を渡すことができる
primary_key n/a Doctrine フィールド名フォーマットでのプライマリキーのカラム名 (オプションとして、提供されなければイントロスペクトされます)。テーブルが複数のプライマリキーを持つ場合配列を渡すこともできます
connection n/a Doctrine のコネクション (デフォルトは null)
throw_global_error n/a グローバルエラー (デフォルトは false) もしくはカラムのオプション配列に関連した最初のフィールドに結びつけられたエラーを投げるかどうか