mirror of
https://github.com/yiisoft/yii.git
synced 2026-03-06 08:14:21 +01:00
374 lines
16 KiB
Plaintext
374 lines
16 KiB
Plaintext
モデルの作成
|
||
==============
|
||
|
||
フォームに必要なHTMLコードを書く前に、エンドユーザから、どの様なタイプの
|
||
データが送られてくる事を期待するか、どの様なルールが適用されるべきかを
|
||
決定します。モデルクラスはこれらの情報を記録するために
|
||
使用することができます。モデルはサブセクション
|
||
[Model](/doc/guide/basics.model) で定義されているように、
|
||
ユーザーの入力を保持し、入力チェックを行う中心的な場所です。
|
||
|
||
ユーザーの入力をどのように扱うかによって、2つのタイプのモデルを
|
||
作成することができます。もしユーザーの入力が収集され、
|
||
使用された後に破棄される場合は、 [form model](/doc/guide/basics.model)
|
||
を作成しましょう;もしユーザーの入力が収集され、データベースへ保存される場合
|
||
は代わりに [active record](/doc/guide/database.ar) を使いましょう。
|
||
両方のモデルは共通のインターフェースとして定義された [CModel]
|
||
という基底クラスを必要とします。
|
||
|
||
> Note|注意: このセクションでは例として form model を主に扱いますが、
|
||
[active record](/doc/guide/database.ar) においても同様なことが可能です。
|
||
|
||
モデルクラスの定義
|
||
--------------------
|
||
|
||
以下では、ログインページでユーザーの入力を収集する為に使用される
|
||
`LoginForm` モデルクラスを作成します。ログインで扱う情報は
|
||
認証時にのみ必要で、保存される必要はありませんので、`LoginForm`
|
||
のモデルは form model として作成します。
|
||
|
||
~~~
|
||
[php]
|
||
class LoginForm extends CFormModel
|
||
{
|
||
public $username;
|
||
public $password;
|
||
public $rememberMe=false;
|
||
}
|
||
~~~
|
||
|
||
３つの属性が `LoginForm` の中で宣言されています: `$username`、`$password`、
|
||
そして `$rememberMe`です。これらはユーザーの入力したユーザー名とパスワード、
|
||
そして、ユーザーがログイン情報を保存するかどうかのオプションを保持する為に
|
||
用いられます。`$rememberMe` は、デフォルトで `false` になっているので、
|
||
ログインフォームに表示される結びついたオプションは、初期状態では
|
||
チェックされてない状態となります。
|
||
|
||
> Info|情報: ここでは、これらのメンバ変数を普通のプロパティと区別する為に、
|
||
プロパティと呼ばずに *属性* (attribute) と呼びます。属性は主に、
|
||
ユーザの入力やデータベースのデータを保持する為に用いられるプロパティです。
|
||
|
||
バリデーションルールの宣言
|
||
--------------------------
|
||
|
||
ユーザがインプットを送信し、モデルが値を受け取った際、私たちは
|
||
その値を使用する前に正しい値であるか検証する必要があります。
|
||
これはインプットに対して、セットになったルールのバリデーション（検証）
|
||
を実行する事によって成し遂げられます。バリデーションルールは `rules()`
|
||
メソッドの中で定義し、このメソッドはルールの構成を配列として
|
||
返さなければいけません。
|
||
|
||
~~~
|
||
[php]
|
||
class LoginForm extends CFormModel
|
||
{
|
||
public $username;
|
||
public $password;
|
||
public $rememberMe=false;
|
||
|
||
public function rules()
|
||
{
|
||
return array(
|
||
array('username, password', 'required'),
|
||
array('password', 'authenticate'),
|
||
);
|
||
}
|
||
|
||
public function authenticate($attribute,$params)
|
||
{
|
||
if(!$this->hasErrors()) // インプットエラーが無い場合にのみ認証を行います
|
||
{
|
||
$identity=new UserIdentity($this->username,$this->password);
|
||
if($identity->authenticate())
|
||
{
|
||
$duration=$this->rememberMe ? 3600*24*30 : 0; // 30 days
|
||
Yii::app()->user->login($identity,$duration);
|
||
}
|
||
else
|
||
$this->addError('password','Incorrect password.');
|
||
}
|
||
}
|
||
}
|
||
~~~
|
||
|
||
上記のコードは `username` と `password` の両方が必須であり、`password`
|
||
は認証に掛けられなければならない事を示しています。
|
||
|
||
`rules()` によって返される、それぞれのルールは下記の様なフォーマット
|
||
でなければなりません:
|
||
|
||
~~~
|
||
[php]
|
||
array('AttributeList', 'Validator', 'on'=>'ScenarioList', ...additional options)
|
||
~~~
|
||
|
||
`AttributeList` の箇所は、ルールによって検証されなければならない属性
|
||
(attribute)の名前がカンマ区切りの文字列として入ります; `Validator`
|
||
はどのようなバリデーションが適用されなければならないかを示しています;
|
||
`on` パラメータはオプションで、ルールが適用されるシナリオのリスト
|
||
を示しています; そして追加のオプション(additional option)の箇所は
|
||
名前-値 のペアで、結びついたバリデータのプロパティの値を初期化する為に
|
||
使用されます。
|
||
|
||
バリデーションルールの中で `Validator` を指定するには３つの方法があります。
|
||
ひとつ目に、上記の `authenticate` の例の様に、`Validator` はモデルクラス
|
||
の中のメソッド名を取る事ができます。バリデータメソッドは下記の様な書式
|
||
でなければなりません:
|
||
|
||
~~~
|
||
[php]
|
||
/**
|
||
* @param string the name of the attribute to be validated
|
||
* @param array options specified in the validation rule
|
||
*/
|
||
public function ValidatorName($attribute,$params) { ... }
|
||
~~~
|
||
|
||
二つ目に、`Validator` はバリデータクラスの名前にする事ができます。
|
||
ルールが適用されたとき、バリデータクラスのインスタンスが作成され、
|
||
実際の検証が行われます。追加のオプションの値は、インスタンスの属性の値を
|
||
初期化する為に用いられます。バリデータクラスは [CValidator]
|
||
を継承しなければいけません。
|
||
|
||
> Note|注意: アクティブレコードモデルでルールを定義する場合、`on`
|
||
という名前の特別なオプションを使用する事ができます。このオプションは
|
||
`'insert'` か `'update'` のどちらかにする事が可能で、レコードのインサート
|
||
の時のみにルールが適用されるか、アップデートの時のみにルールが
|
||
適用されるかをそれぞれ指定することが出来ます。もしセットされていない場合、
|
||
ルールは `save()` がコールされた時に両方のケースで適用されます。
|
||
|
||
三つ目に、`Validator` は予め定義されたバリデータクラスの
|
||
エイリアスを用いる事が出来ます。上記の例にあるように、`required` は
|
||
[CRequiredValidator] のエイリアスで、これは属性の値が、空の値では無い
|
||
と検証された事を保証します。下記は予め定義されたバリデータの
|
||
エイリアスの完全なリストです:
|
||
|
||
- `boolean`: [CBooleanValidator]のエイリアスで、属性の値が
|
||
[CBooleanValidator::trueValue]かまたは[CBooleanValidator::falseValue]である事を確認します。
|
||
|
||
- `captcha`: [CCaptchaValidator] のエイリアスで、属性の値が
|
||
[CAPTCHA](http://en.wikipedia.org/wiki/Captcha)で表示された
|
||
ベリフィケーションコードと等しい事を確認します。
|
||
|
||
- `compare`: [CCompareValidator] のエイリアスで、 属性の値が、
|
||
もう一つの属性、または定数と等しい事を確認します。
|
||
|
||
- `email`: [CEmailValidator] のエイリアスで、属性の値が正式な
|
||
Eメールアドレスである事を確認します。
|
||
|
||
- `default`: [CDefaultValueValidator]のエイリアスで、指定した属性にデフォルト地を代入します。
|
||
|
||
- `exist`: [CExistValidator]のエイリアスで、属性値が指定されたテーブルの列に存在することを保証します。
|
||
|
||
- `file`: [CFileValidator] のエイリアスで、属性の値にアップロード
|
||
されたファイルの名前が入っている事を確認します。
|
||
|
||
- `filter`: [CFilterValidator] のエイリアスで、 属性の値を
|
||
フィルタによって変形します。
|
||
|
||
- `in`: [CRangeValidator] のエイリアスで、属性の値が、
|
||
予め定めた値のリストの中にある事を確認します。
|
||
|
||
- `length`: [CStringValidator] のエイリアスで、
|
||
データの長さが特定の範囲内にある事を確認します。
|
||
|
||
- `match`: [CRegularExpressionValidator] のエイリアスで、
|
||
データが正規表現にマッチする事を確認します。
|
||
|
||
- `numerical`: [CNumberValidator] のエイリアスで、
|
||
データが数値として妥当であるかを確認します。
|
||
|
||
- `required`: [CRequiredValidator] のエイリアスで、
|
||
属性が空でない事を確認します。
|
||
|
||
- `type`: [CTypeValidator] のエイリアスでデータが
|
||
特定の型である事を確認します。
|
||
|
||
- `unique`: [CUniqueValidator] のエイリアスで、データが
|
||
データベースのテーブルのカラムで一意な値である事を確認します。
|
||
|
||
- `url`: [CUrlValidator] のエイリアスで、データが妥当なURLである事
|
||
を確認します。
|
||
|
||
下記は予め定義されたバリデータを使用した例のリストです:
|
||
|
||
~~~
|
||
[php]
|
||
// username は必須です。
|
||
array('username', 'required'),
|
||
// username の長さが3から12の間である事を確認します。
|
||
array('username', 'length', 'min'=>3, 'max'=>12),
|
||
// 登録シナリオでは、パスワードとパスワード2は一致する必要があります。
|
||
array('password', 'compare', 'compareAttribute'=>'password2', 'on'=>'register'),
|
||
// ログインシナリオでは、パスワードは認証されなければなりません。
|
||
array('password', 'authenticate', 'on'=>'login'),
|
||
~~~
|
||
|
||
属性への代入をセキュアにする
|
||
--------------------------------
|
||
|
||
> 注意：シナリオベースでの属性への代入は1.0.2から利用可能です。
|
||
|
||
モデルインスタンスが作成した後、多くの場合は属性値にユーザからの入力値を代入する必要があります。
|
||
これは以下のように一括代入を使うと容易に行えます。
|
||
|
||
~~~
|
||
[php]
|
||
$model=new LoginForm;
|
||
$model->scenario='login';
|
||
if(isset($_POST['LoginForm']))
|
||
$model->attributes=$_POST['LoginForm'];
|
||
~~~
|
||
|
||
> Note|注意: [scenario|CModel::scenario] プロパティは、バージョン 1.0.4
|
||
> 以降で利用可能です。一括代入では、どの属性を一括代入できるかを決定するために、
|
||
> このプロパティ値が利用されます。
|
||
> バージョン 1.0.2 と 1.0.3 では、特定のシナリオに一括代入を行うために、
|
||
> 下記の方法を使用する必要があります。
|
||
>
|
||
> ~~~
|
||
> [php]
|
||
> $model->setAttributes($_POST['LoginForm'], 'login');
|
||
> ~~~
|
||
|
||
最後の文は、`login` シナリオの対応モデル属性に `$_POST['LoginForm']` の
|
||
すべてのエントリを一括代入します。
|
||
これは、下記の代入と同等です。
|
||
|
||
~~~
|
||
[php]
|
||
foreach($_POST['LoginForm'] as $name=>$value)
|
||
{
|
||
if($name is a safe attribute)
|
||
$model->$name=$value;
|
||
}
|
||
~~~
|
||
|
||
各属性が一括代入しても安全かどうかの判断は、
|
||
`safeAttributes`メソッドの戻り値と、指定されたシナリオによって決定されます。
|
||
デフォルトでは、[CFormModel]のすべてのパブリックメンバプロパティが安全と返されます。
|
||
一方で [CActiveRecord]では、プライマリキーを除いたテーブルのカラムすべてが安全と返されます。
|
||
このメソッドをオーバーライドして、安全な属性をシナリオによって制限することができます。
|
||
例えば、ユーザモデルはたくさんの属性を持ちますが、`login`シナリオでは`username`と`password`
|
||
しか使わないので、以下のようにして制限を加えます。
|
||
|
||
~~~
|
||
[php]
|
||
public function safeAttributes()
|
||
{
|
||
return array(
|
||
parent::safeAttributes(),
|
||
'login' => 'username, password',
|
||
);
|
||
}
|
||
~~~
|
||
|
||
より正確には、`safeAttributes`メソッドの戻り値は以下のような構造です。
|
||
|
||
~~~
|
||
[php]
|
||
array(
|
||
// これらの属性は下で明示的に指定されたしなりの以外のすべてのケースで一括代入の対象になる
|
||
'attr1, attr2, ...',
|
||
*
|
||
// これらの属性はシナリオ1でのみ一括代入される
|
||
'scenario1' => 'attr2, attr3, ...',
|
||
*
|
||
// これらの属性はシナリオ2でのみ一括代入される
|
||
'scenario2' => 'attr1, attr3, ...',
|
||
)
|
||
~~~
|
||
|
||
モデルでシナリオを必要としない場合(例：常にひとつのシナリオで使われる、
|
||
すべてのシナリオで同じ安全な属性のセットを使う)、戻り値は単純な文字列でもかまいません。
|
||
|
||
~~~
|
||
[php]
|
||
'attr1, attr2, ...'
|
||
~~~
|
||
|
||
安全でない属性にデータを代入するには、以下のように個々に代入式を書く必要があります。
|
||
|
||
~~~
|
||
[php]
|
||
$model->permission='admin';
|
||
$model->id=1;
|
||
~~~
|
||
|
||
バリデーションの始動
|
||
---------------------
|
||
|
||
モデルにユーザからの入力値をセットしたら、
|
||
バリデーションを始動する為に、[CModel::validate()] をコールする事
|
||
が出来ます。このメソッドは、一つのエラーも起こらずに、バリデーションが
|
||
成功したかどうかを示す値を返します。アクティブレコードモデルでは、
|
||
モデルをデータベースに保存する為に、 [save()|CActiveRecord::save]
|
||
をコールした時点で、バリデーションは自動的に動作します。
|
||
|
||
[CModel::validate()]を呼ぶ際に、シナリオパラメータを指定することができます。
|
||
指定されたシナリオに当てはまるバリデーションルールのみが実行されます。
|
||
シナリオに当てはまるバリデーションデータは、ルールの `on` オプションが設定されていないか、
|
||
指定されたシナリオ名を含むものです。
|
||
[CModel::validate()]を呼ぶ際にシナリオを指定しないと、`on` オプションが設定されていないルールのみが実行されます。
|
||
|
||
例えば、以下の評価式を実行して、ユーザ登録時のバリデーションをおこうなうことができます。
|
||
|
||
~~~
|
||
[php]
|
||
$model->scenario='register';
|
||
$model->validate();
|
||
~~~
|
||
|
||
> Note: [scenario|CModel::scenario]プロパティはバージョン1.0.4から利用可能です。
|
||
> validationメソッドはどのルールがチェックされるかどうかをこのプロパティによって決定します。
|
||
> バージョン1.0.2と1.0.3では、シナリオベースのバリデーションを実行する際に以下のようにする必要があります。
|
||
>
|
||
> ~~~
|
||
> [php]
|
||
> $model->validate('register');
|
||
> ~~~
|
||
|
||
バリデーションルールはフォームモデルクラスで以下のように宣言できます。
|
||
|
||
~~~
|
||
[php]
|
||
public function rules()
|
||
{
|
||
return array(
|
||
array('username, password', 'required'),
|
||
array('password_repeat', 'required', 'on'=>'register'),
|
||
array('password', 'compare', 'on'=>'register'),
|
||
);
|
||
}
|
||
~~~
|
||
|
||
結果として、最初のルールはすべてのシナリオに適用され、
|
||
そのほかの二つのシナリオは`register`シナリオの場合のみ適用されます。
|
||
|
||
> 注意: シナリオベースのバリデーションはバージョン1.0.1から利用可能です。
|
||
|
||
|
||
バリデーションエラーの回収
|
||
----------------------------
|
||
|
||
バリデーションエラーがあるかどうかをチェックする為に [CModel::hasErrors()]
|
||
を使用する事ができ、もしエラーがある場合、エラーメッセージ獲得の為に
|
||
[CModel::getErrors()] を使用する事ができます。メソッドは両方とも、
|
||
個別の属性か全ての属性に対して使用する事が出来ます。
|
||
|
||
属性のラベル
|
||
----------------
|
||
|
||
フォームをデザインする時、それぞれのインプットフィールドにラベルの表示
|
||
が必要となる事が度々あります。ラベルはユーザに、どの様な種類の情報を
|
||
フィールドに入力するかを伝えます。ビューの中にラベルを直接書き込む事も可能
|
||
ですが、結びついたモデルの中で定めた方がより柔軟で便利なことが多いでしょう。
|
||
|
||
デフォルトでは、[CModel] は単純に属性の名前をラベルとして返します。
|
||
これは [attributeLabels()|CModel::attributeLabels] メソッドを
|
||
オーバーライドする事でカスタマイズ可能です。次のサブセクション
|
||
に見るように、モデルの中でのラベルの定義は、より早く、
|
||
力強いフォームの作成を私達にもたらします。
|
||
|
||
<div class="revision">$Id: form.model.txt 1423 2009-04-05 21:36:33Z qiang.xue $</div>
|