Yii Framework Official Guide Series 17 - Using Forms: Creating Models-PHP Tutorial-php.cn

Before writing the HTML code required for the form, we should first determine the type of data input from the end user and what the data should conform to Such rules. Model classes can be used to record this information. As defined in the Models chapter, a model is the central location for storing user input and validating those inputs.

Depending on how the data entered by the user is used, we can create two types of models. If user input is collected, used and then discarded, we should create a form model; if user input is collected and then saved to a database, we should use an Active Record. Both types of models share the same base class CModel , which defines the common interface required by the form.

Note: We mainly use the form model in the examples in this section. However, the same operation can also be applied to Active Record models.

1. Define the model class

Below we create a LoginForm model class to collect user input in a login page. Since the login information is only used to authenticate the user and does not need to be saved, we create LoginForm as a form model.

class LoginForm extends CFormModel
{
    public $username;
    public $password;
    public $rememberMe=false;
}

Copy after login

LoginForm defines three attributes: $username , $password and $rememberMe. They are used to save the username and password entered by the user, as well as the option of whether the user wants to remember his login. Since $rememberMe has a default value of false, the corresponding option will be unchecked when initially displayed in the login form.

Information: We call these member variables attributes instead of properties to distinguish them from ordinary properties. . An attribute is a property primarily used to store data from user input or database.

2. Declare validation rules

Once the user submits his input and the model is populated, we need to ensure that the user's input is valid before use. This is achieved by validating the user's input against a series of rules. We specify these validation rules in the rules() method, which should return an array of rule configurations.

class LoginForm extends CFormModel
{
    public $username;
    public $password;
    public $rememberMe=false;

    private $_identity;

    public function rules()
    {
        return array(
            array('username, password', 'required'),
            array('rememberMe', 'boolean'),
            array('password', 'authenticate'),
        );
    }

    public function authenticate($attribute,$params)
    {
        $this->_identity=new UserIdentity($this->username,$this->password);
        if(!$this->_identity->authenticate())
            $this->addError('password','错误的用户名或密码。');
    }
}

Copy after login

The above code specifies: username and password are required The item, password should be authenticated, and rememberMe should be a boolean value.

rules() Each rule returned must be in the following format:

array('AttributeList', 'Validator', 'on'=>'ScenarioList', ...附加选项)

Copy after login

Among them AttributeList (attribute list) is the attribute list string that needs to be verified by this rule. Each attribute name is separated by commas; Validator (validator) specifies to perform verification The type; the on parameter is optional and specifies the list of scenarios to which this rule should be applied; additional options are an array of name-value pairs used to initialize the attribute values of the corresponding validator.

There are three ways to specify Validator in validation rules.

First, Validator can be the name of a method in the model class, just like authenticate in the example above. The verification method must be the following structure:

/**
 * @param string 所要验证的特性的名字
 * @param array 验证规则中指定的选项
 */
public function ValidatorName($attribute,$params) { ... }

Copy after login

Second,

Validator can Is the name of a validator class . When this rule is applied, an instance of the validator class will be created to perform the actual validation. Additional options in the rule are used to initialize the instance's attribute values. The validator class must inherit from CValidator.

Third,

Validator can be an alias of a predefined validator class. In the example above, the required name is an alias for CRequiredValidator, which is used to ensure that the property being validated is not empty. Here is the complete list of predefined validator aliases:

#boolean: Alias for CBooleanValidator , make sure the attribute has a CBooleanValidator::trueValue or CBooleanValidator::falseValue value .
captcha: Alias for CCaptchaValidator, ensuring that the attribute value is equal to the verification code displayed in the CAPTCHA.
compare: Alias for CCompareValidator that ensures that a property is equal to another property or constant.
email: Alias for CEmailValidator, ensuring the attribute is a valid email address.
default: Alias of CDefaultValueValidator, specifying the default value of the attribute.
exist: CExistValidator 的别名，确保特性值可以在指定表的列中可以找到。
file: CFileValidator 的别名，确保特性含有一个上传文件的名字。
filter: CFilterValidator 的别名，通过一个过滤器改变此特性。
in: CRangeValidator 的别名，确保数据在一个预先指定的值的范围之内。
length: CStringValidator 的别名，确保数据的长度在一个指定的范围之内。
match: CRegularExpressionValidator 的别名，确保数据可以匹配一个正则表达式。
numerical: CNumberValidator 的别名，确保数据是一个有效的数字。
required: CRequiredValidator 的别名，确保特性不为空。
type: CTypeValidator 的别名，确保特性是指定的数据类型。
unique: CUniqueValidator 的别名，确保数据在数据表的列中是唯一的。
url: CUrlValidator 的别名，确保数据是一个有效的 URL。

下面我们列出了几个只用这些预定义验证器的示例：

// 用户名为必填项
array('username', 'required'),
// 用户名必须在 3 到 12 个字符之间
array('username', 'length', 'min'=>3, 'max'=>12),
// 在注册场景中，密码password必须和password2一致。
array('password', 'compare', 'compareAttribute'=>'password2', 'on'=>'register'),
// 在登录场景中，密码必须接受验证。
array('password', 'authenticate', 'on'=>'login'),

Copy after login

3. 安全的特性赋值

在一个类的实例被创建后，我们通常需要用最终用户提交的数据填充它的特性。这可以通过如下块赋值（massive assignment）方式轻松实现：

$model=new LoginForm;
if(isset($_POST['LoginForm']))
    $model->attributes=$_POST['LoginForm'];

Copy after login

最后的表达式被称作 块赋值（massive assignment），它将 $_POST['LoginForm'] 中的每一项复制到相应的模型特性中。这相当于如下赋值方法：

foreach($_POST['LoginForm'] as $name=>$value)
{
    if($name 是一个安全的特性)
        $model->$name=$value;
}

Copy after login

检测特性的安全非常重要，例如，如果我们以为一个表的主键是安全的而暴露了它，那么攻击者可能就获得了一个修改记录的主键的机会，从而篡改未授权给他的内容。

检测特性安全的策略在版本 1.0 和 1.1 中是不同的，下面我们将分别讲解：

1.1 中的安全特性

在版本 1.1 中，特性如果出现在相应场景的一个验证规则中，即被认为是安全的。例如：

array('username, password', 'required', 'on'=>'login, register'),
array('email', 'required', 'on'=>'register'),

Copy after login

如上所示， username 和 password 特性在 login 场景中是必填项。而 username, password 和 email 特性在register 场景中是必填项。于是，如果我们在 login 场景中执行块赋值，就只有 username 和 password 会被块赋值。因为只有它们出现在 login 的验证规则中。另一方面，如果场景是 register ，这三个特性就都可以被块赋值。

// 在登录场景中
$model=new User('login');
if(isset($_POST['User']))
    $model->attributes=$_POST['User'];

// 在注册场景中
$model=new User('register');
if(isset($_POST['User']))
    $model->attributes=$_POST['User'];

Copy after login

那么为什么我们使用这样一种策略来检测特性是否安全呢？背后的基本原理就是：如果一个特性已经有了一个或多个可检测有效性的验证规则，那我们还担心什么呢？

请记住，验证规则是用于检查用户输入的数据，而不是检查我们在代码中生成的数据（例如时间戳，自动产生的主键）。因此，不要为那些不接受最终用户输入的特性添加验证规则。

有时候，我们想声明一个特性是安全的，即使我们没有为它指定任何规则。例如，一篇文章的内容可以接受用户的任何输入。我们可以使用特殊的 safe 规则实现此目的：

array('content', 'safe')

Copy after login

为了完成起见，还有一个用于声明一个属性为不安全的 unsafe 规则：

array('permission', 'unsafe')

Copy after login

unsafe 规则并不常用，它是我们之前定义的安全特性的一个例外。

1.0 中的安全特性

在版本1.0中,决定一个数据项是否是安全的,基于一个名为 safeAttributes 方法的返回值和数据项被指定的场景. 默认的,这个方法返回所有公共成员变量作为 CFormModel 的安全特性,而它也返回了除了主键外, 表中所有字段名作为 CActiveRecord的安全特性.我们可以根据场景重写这个方法来限制安全特性 .例如, 一个用户模型可以包含很多特性,但是在 login 场景.里,我们只能使用 username 和 password 特性.我们可以按照如下来指定这一限制 :

public function safeAttributes()
{
    return array(
        parent::safeAttributes(),
        'login' => 'username, password',
    );
}

Copy after login

safeAttributes 方法更准确的返回值应该是如下结构的 :

array(
   // these attributes can be massively assigned in any scenario
   // that is not explicitly specified below
   'attr1, attr2, ...',
     *
   // these attributes can be massively assigned only in scenario 1
   'scenario1' => 'attr2, attr3, ...',
     *
   // these attributes can be massively assigned only in scenario 2
   'scenario2' => 'attr1, attr3, ...',
)

Copy after login

如果模型不是场景敏感的(比如,它只在一个场景中使用,或者所有场景共享了一套同样的安全特性),返回值可以是如下那样简单的字符串.

'attr1, attr2, ...'

Copy after login

而那些不安全的数据项,我们需要使用独立的赋值语句来分配它们到相应的特性.如下所示:

$model->permission='admin';
$model->id=1;

Copy after login

4. 触发验证

一旦模型被用户提交的数据填充，我们就可以调用 CModel::validate() 出发数据验证进程。此方法返回一个指示验证是否成功的值。对 CActiveRecord 模型来说，验证也可以在我们调用其 CActiveRecord::save() 方法时自动触发。

我们可以使用 scenario 设置场景属性，这样，相应场景的验证规则就会被应用。

验证是基于场景执行的。 scenario 属性指定了模型当前用于的场景和当前使用的验证规则集。例如，在 login场景中，我们只想验证用户模型中的 username 和 password 输入；而在 register 场景中，我们需要验证更多的输入，例如 email, address, 等。下面的例子演示了如何在 register 场景中执行验证：

// 在注册场景中创建一个  User 模型。等价于：
// $model=new User;
// $model->scenario='register';
$model=new User('register');

// 将输入的值填充到模型
$model->attributes=$_POST['User'];

// 执行验证
if($model->validate())   // if the inputs are valid
    ...
else
    ...

Copy after login

规则关联的场景可以通过规则中的 on 选项指定。如果 on 选项未设置，则此规则会应用于所有场景。例如：

public function rules()
{
    return array(
        array('username, password', 'required'),
        array('password_repeat', 'required', 'on'=>'register'),
        array('password', 'compare', 'on'=>'register'),
    );
}

Copy after login

第一个规则将应用于所有场景，而第二个将只会应用于 register 场景。