付録 B - バリデータ

はじめに

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

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

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 が投げられます。

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

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

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

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

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

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

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

バリデータスキーマ

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

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

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

バリデータ

• sfValidatorString
• sfValidatorRegex
• sfValidatorEmail
• sfValidatorUrl
• sfValidatorInteger
• sfValidatorNumber
• sfValidatorBoolean
• sfValidatorChoice
• sfValidatorPass
• sfValidatorCallback
• sfValidatorDate
• sfValidatorTime
• sfValidatorDateTime
• sfValidatorDateRange
• sfValidatorFile
• sfValidatorAnd
• sfValidatorOr
• sfValidatorSchema
• sfValidatorSchemaCompare
• sfValidatorSchemaFilter
• sfValidatorI18nChoiceCountry
• sfValidatorI18nChoiceLanguage
• sfValidatorI18nTimezone
• sfValidatorPropelChoice
• sfValidatorPropelUnique
• sfValidatorDoctrineChoice
• sfValidatorDoctrineUnique

シンプルなバリデータ

sfValidatorString

スキーマバリデータ: No

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

sfValidatorRegex

スキーマバリデータ: No

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

sfValidatorEmail

スキーマバリデータ: No

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

sfValidatorUrl

スキーマバリデータ: No

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

sfValidatorInteger

スキーマバリデータ: No

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

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

sfValidatorNumber

スキーマバリデータ: No

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

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

sfValidatorBoolean

スキーマバリデータ: No

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

sfValidatorChoice

スキーマバリデータ: No

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

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'),
));

日付バリデータ

sfValidatorDate

スキーマバリデータ: No

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

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

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

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

sfValidatorTime

スキーマバリデータ: No

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

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

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

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

sfValidatorDateTime

スキーマバリデータ: No

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

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

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

sfValidatorDateRange

スキーマバリデータ: No

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

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

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

ファイルバリデータ

sfValidatorFile

スキーマバリデータ: No

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

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

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 系システムでのみ動作する)

バリデータは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 オプションに 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(),
));

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

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

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

$v->setPostValidator(
  new sfValidatorSchemaCompare('password', '==', 'password_again')
);

埋め込みのバリデータにアクセスするために 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');

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

• 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_error に true がセットされている場合、左側フィールドのエラーが投げられます。

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

sfValidatorSchemaFilter

スキーマバリデータ: Yes

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

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

国際化バリデータ

sfValidatorI18nChoiceCountry

スキーマバリデータ: No

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

sfValidatorI18nChoiceLanguage

スキーマバリデータ: No

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

sfValidatorI18nChoiceTimezone

スキーマバリデータ: No

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

Propel バリデータ

sfValidatorPropelChoice

スキーマバリデータ: No

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

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

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

sfValidatorPropelUnique

スキーマバリデータ: Yes

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

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

Doctrine バリデータ

sfValidatorDoctrineChoice

スキーマバリデータ: No

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

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

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

sfValidatorDoctrineUnique

スキーマバリデータ: Yes

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

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