Caution: You are browsing the legacy symfony 1.x part of this website.
Cover of the book Symfony 5: The Fast Track

Symfony 5: The Fast Track is the best book to learn modern Symfony development, from zero to production. +300 pages showcasing Symfony with Docker, APIs, queues & async tasks, Webpack, SPAs, etc.

付録 B - バリデーター

1.2
Symfony version
1.4
Language

はじめに

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

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.)。

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

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

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

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

sfValidatorRegex

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

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

オプション エラー 説明
pattern invalid PCRE 正規表現のパターン

sfValidatorEmail

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

sfValidatorEmail バリデーターはEメールをバリデートできます。 このバリデーターは sfValidatorRegex を継承します。

sfValidatorUrl

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

sfValidatorUrl バリデーターは HTTP と FTP URLをバリデートできます。 これは sfValidatorRegex を継承します。

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

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 正規表現にマッチする文字列
  • PHP の strtotime() 関数によって解析できる文字列
  • タイムスタンプを表す整数

date_output もしくは datetime_output の書式を適用することで汚染された値は日付に変換されます。

オプション エラー 説明
date_format bad_format 日付がマッチしなければならない正規表現
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 コンストラクターは最初の引数としてバリデーターのリストを受け取ります:

$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

少なくともリストからのバリデーターから汚染された値が通る場合、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(),
));

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 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_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 使用する言語コードの配列

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

このバリデーターは複合主キーを持つモデルに対しては機能しません。

sfValidatorPropelChoiceMany

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

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

note

このバリデーターは入力値を配列として期待します。 文字列が渡されると、これは自動的に配列に変換されます。

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

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

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

このバリデーターは複合主キーを持つモデルに対しては機能しません。

sfValidatorDoctrineChoiceMany

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

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

note

このバリデーターは配列を入力値として期待します。 文字列が渡されると、これは自動的に配列に変換されます。

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

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) もしくはカラムのオプション配列に関連した最初のフィールドに結びつけられたエラーを投げるかどうか