付録 B - バリデーター

はじめに

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

それぞれのバリデーターの詳細内容に飛び込む前に、バリデーターが共通に持つ機能を見てみましょう。

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 によって定義されるデフォルトのエラーメッセージは次のとおりです:

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

sfValidatorBase::setRequiredMessage('This value is required.');
sfValidatorBase::setInvalidMessage('This value is invalid.');

エラーメッセージはプレースホルダーを持つことができます。 プレースホルダーは % で囲まれた文字列です。 実行時にプレースホルダーは置き換えされます。 すべてのエラーメッセージは %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
• sfValidatorPropelChoice
• sfValidatorPropelChoiceMany
• sfValidatorPropelUnique
• sfValidatorDoctrineChoice
• sfValidatorDoctrineChoiceMany
• sfValidatorDoctrineUnique

シンプルなバリデーター

sfValidatorString

スキーマバリデーター: No

sfValidatorString バリデーターは文字列をバリデートして汚染された値を文字列に変換します。

sfValidatorRegex

スキーマバリデーター: No

sfValidatorRegex バリデーターは正規表現に対して文字列をバリデートします。

sfValidatorEmail

スキーマバリデーター: No

sfValidatorEmail バリデーターはEメールをバリデートできます。 このバリデーターは 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 正規表現にマッチする文字列
• 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 コンストラクターは最初の引数としてバリデーターのリストを受け取ります:

$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

少なくともリストからのバリデーターから汚染された値が通る場合、sfValidatorOr バリデーターはその汚染された値をバリデートします。

sfValidatorOr コンストラクターは最初の引数としてバリデーターのリストを受け取ります:

$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 or ==
• sfValidatorSchemaCompare::NOT_EQUAL or !=
• sfValidatorSchemaCompare::LESS_THAN or <
• sfValidatorSchemaCompare::LESS_THAN_EQUAL or <=
• sfValidatorSchemaCompare::GREATER_THAN or >
• sfValidatorSchemaCompare::GREATER_THAN_EQUAL or >=

デフォルトでは、バリデーターはグローバルエラーを投げます。 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 は汚染された値が有効な言語コードであることをバリデートします。

Propelバリデーター

sfValidatorPropelChoice

スキーマバリデーター: No

sfValidatorPropelChoice バリデーターは汚染された値が Propel モデルのレコードのリストの間にあることをバリデートします。

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

汚染された値はレコードの主キーでなければなりません。これは column オプションを渡すことで変更できます。

sfValidatorPropelChoiceMany

スキーマバリデーター: No

sfValidatorPropelChoiceMany バリデーターは汚染された値が Propel モデルのレコードのリストの間にあることをバリデートします。

このバリデーターはショートカットです:

$v = new sfValidatorPropelChoice(array('multiple' => true));

sfValidatorPropelUnique

スキーマバリデーター: Yes

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

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

Doctrine バリデーター

sfValidatorDoctrineChoice

スキーマバリデーター: No

sfValidatorDoctrineChoice バリデーターは汚染された値が Doctrine モデルのレコードのリストの間にあることをバリデートします。

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

汚染された値はレコードの主キーでなければなりません。 これはcolumnオプションを渡すことで変更できます。

sfValidatorDoctrineChoiceMany

スキーマバリデーター: No

sfValidatorDoctrineChoiceMany バリデーターは汚染された値が Doctrine モデルのレコードのリストの間にあることをバリデートします。

このバリデーターはsfValidatorDoctrineChoice バリデーターからのすべてのオプションを継承します。

sfValidatorDoctrineUnique

スキーマバリデーター: Yes

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

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