4 关注者

类 yii\base\Model

继承yii\base\Model » yii\base\Component » yii\base\BaseObject
实现ArrayAccess, IteratorAggregate, yii\base\Arrayable, yii\base\Configurable, yii\base\StaticInstanceInterface
使用特征yii\base\ArrayableTrait, yii\base\StaticInstanceTrait
子类yii\base\DynamicModel, yii\data\ActiveDataFilter, yii\data\DataFilter, yii\db\ActiveRecord, yii\db\BaseActiveRecord
可用版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/base/Model.php

Model 是数据模型的基类。

Model 实现以下常用的功能

  • 属性声明:默认情况下,每个公共类成员都被视为模型属性
  • 属性标签:每个属性可能与一个标签相关联,用于显示目的
  • 批量属性赋值
  • 基于场景的验证

Model 在执行数据验证时还会引发以下事件

您可以直接使用 Model 存储模型数据,或扩展它以进行自定义。

有关 Model 的更多详细信息和使用信息,请参阅有关模型的 指南文章

公共属性

隐藏继承的属性

属性 类型 描述 定义于
$activeValidators yii\validators\Validator[] 适用于当前 $scenario 的验证器。 yii\base\Model
$attributes 数组 属性值(名称 => 值)。 yii\base\Model
$behaviors yii\base\Behavior[] 附加到此组件的行为列表。 yii\base\Component
$errors 数组 所有属性或指定属性的错误。 yii\base\Model
$firstErrors 数组 第一个错误。 yii\base\Model
$iterator ArrayIterator 用于遍历列表中项目的迭代器。 yii\base\Model
$scenario 字符串 此模型所在的场景。 yii\base\Model
$validators ArrayObject|yii\validators\Validator[] 模型中声明的所有验证器。 yii\base\Model

公共方法

隐藏继承的方法

方法 描述 定义于
__call() 调用不是类方法的命名方法。 yii\base\Component
__clone() 此方法在通过克隆现有对象创建对象后被调用。 yii\base\Model
__construct() 构造函数。 yii\base\BaseObject
__get() 返回组件属性的值。 yii\base\Component
__isset() 检查属性是否已设置,即定义且不为空。 yii\base\Component
__set() 设置组件属性的值。 yii\base\Component
__unset() 将组件属性设置为 null。 yii\base\Component
activeAttributes() 返回当前场景中受验证影响的属性名称列表。 yii\base\Model
addError() 将新错误添加到指定属性。 yii\base\Model
addErrors() 添加错误列表。 yii\base\Model
afterValidate() 此方法在验证结束后被调用。 yii\base\Model
attachBehavior() 将行为附加到此组件。 yii\base\Component
attachBehaviors() 将行为列表附加到组件。 yii\base\Component
attributeHints() 返回属性提示。 yii\base\Model
attributeLabels() 返回属性标签。 yii\base\Model
attributes() 返回属性名称列表。 yii\base\Model
beforeValidate() 此方法在验证开始之前被调用。 yii\base\Model
behaviors() 返回此组件应表现为的行为列表。 yii\base\Component
canGetProperty() 返回一个值,指示是否可以读取属性。 yii\base\Component
canSetProperty() 返回一个值,指示是否可以设置属性。 yii\base\Component
className() 返回此类的完全限定名称。 yii\base\BaseObject
clearErrors() 删除所有属性或单个属性的错误。 yii\base\Model
createValidators() 根据 rules() 中指定的验证规则创建验证器对象。 yii\base\Model
detachBehavior() 从组件中分离行为。 yii\base\Component
detachBehaviors() 从组件中分离所有行为。 yii\base\Component
ensureBehaviors() 确保 behaviors() 中声明的行为已附加到此组件。 yii\base\Component
extraFields() 返回可进一步扩展的字段列表,并由 toArray() 返回。 yii\base\ArrayableTrait
fields() 返回应由 toArray() 在未指定特定字段时默认返回的字段列表。 yii\base\Model
formName() 返回此模型类应使用的表单名称。 yii\base\Model
generateAttributeLabel() 根据给定的属性名称生成用户友好的属性标签。 yii\base\Model
getActiveValidators() 返回适用于当前 $scenario 的验证器。 yii\base\Model
getAttributeHint() 返回指定属性的文本提示。 yii\base\Model
getAttributeLabel() 返回指定属性的文本标签。 yii\base\Model
getAttributes() 返回属性值。 yii\base\Model
getBehavior() 返回命名行为对象。 yii\base\Component
getBehaviors() 返回附加到此组件的所有行为。 yii\base\Component
getErrorSummary() 将所有属性的错误作为一维数组返回。 yii\base\Model
getErrors() 返回所有属性或单个属性的错误。 yii\base\Model
getFirstError() 返回指定属性的第一个错误。 yii\base\Model
getFirstErrors() 返回模型中每个属性的第一个错误。 yii\base\Model
getIterator() 返回用于遍历模型中属性的迭代器。 yii\base\Model
getScenario() 返回此模型所使用的场景。 yii\base\Model
getValidators() 返回 rules() 中声明的所有验证器。 yii\base\Model
hasErrors() 返回一个值,指示是否存在任何验证错误。 yii\base\Model
hasEventHandlers() 返回一个值,指示是否将任何处理程序附加到命名事件。 yii\base\Component
hasMethod() 返回一个值,指示是否定义了方法。 yii\base\Component
hasProperty() 返回一个值,指示是否为此组件定义了属性。 yii\base\Component
init() 初始化对象。 yii\base\BaseObject
instance() 返回静态类实例,可用于获取元信息。 yii\base\StaticInstanceTrait
isAttributeActive() 返回一个值,指示属性在当前场景中是否处于活动状态。 yii\base\Model
isAttributeRequired() 返回一个值,指示属性是否必需。 yii\base\Model
isAttributeSafe() 返回一个值,指示属性是否可以进行批量赋值。 yii\base\Model
load() 使用输入数据填充模型。 yii\base\Model
loadMultiple() 使用来自最终用户的数据填充一组模型。 yii\base\Model
off() 从此组件中分离现有的事件处理程序。 yii\base\Component
offsetExists() 返回指定偏移量处是否存在元素。 yii\base\Model
offsetGet() 返回指定偏移量处的元素。 yii\base\Model
offsetSet() 设置指定偏移处的元素。 yii\base\Model
offsetUnset() 将指定偏移处的元素值设置为 null。 yii\base\Model
on() 将事件处理程序附加到事件。 yii\base\Component
onUnsafeAttribute() 当不安全属性被大量分配时,将调用此方法。 yii\base\Model
rules() 返回属性的验证规则。 yii\base\Model
safeAttributes() 返回在当前场景中可以被大量分配的属性名称。 yii\base\Model
scenarios() 返回场景列表和相应的活动属性。 yii\base\Model
setAttributes() 以大量方式设置属性值。 yii\base\Model
setScenario() 设置模型的场景。 yii\base\Model
toArray() 将模型转换为数组。 yii\base\ArrayableTrait
trigger() 触发事件。 yii\base\Component
validate() 执行数据验证。 yii\base\Model
validateMultiple() 验证多个模型。 yii\base\Model

受保护的方法

隐藏继承的方法

方法 描述 定义于
extractFieldsFor() 从给定根字段的字段集合中提取嵌套字段。嵌套字段用点 (.) 分隔。例如:"item.id" 上面的示例将提取 "id"。 yii\base\ArrayableTrait
extractRootFields() 从嵌套字段中提取根字段名称。 yii\base\ArrayableTrait
resolveFields() 确定哪些字段可以由 toArray() 返回。 yii\base\ArrayableTrait

事件

隐藏继承的事件

事件 类型 描述 定义于
EVENT_AFTER_VALIDATE yii\base\Event validate() 结束时触发的事件 yii\base\Model
EVENT_BEFORE_VALIDATE yii\base\ModelEvent validate() 开始时触发的事件。 yii\base\Model

常量

隐藏继承的常量

常量 描述 定义于
SCENARIO_DEFAULT 'default' 默认场景的名称。 yii\base\Model

属性详细信息

隐藏继承的属性

$activeValidators 公共属性

适用于当前 $scenario 的验证器。

$attributes 公共属性

属性值(名称 => 值)。

public array $attributes null
$errors 公共属性

所有属性或指定属性的错误。如果无错误,则返回空数组。有关详细信息,请参阅 getErrors()。请注意,在返回所有属性的错误时,结果是一个二维数组,例如:`php [ 'username' => [ 'Username is required.', 'Username must contain only word characters.', ], 'email' => [ 'Email address is invalid.', ] ] `

public array $errors null
$firstErrors 公共属性

第一个错误。数组键是属性名称,数组值是相应的错误消息。如果无错误,则返回空数组。

public array $firstErrors null
$iterator 公共只读属性

用于遍历列表中项目的迭代器。

$scenario 公共属性

此模型所处的场景。默认为 SCENARIO_DEFAULT

public string $scenario null
$validators 公共属性

模型中声明的所有验证器。

方法详细信息

隐藏继承的方法

__call() 公共方法

定义于: yii\base\Component::__call()

调用不是类方法的命名方法。

此方法将检查任何附加的行为是否具有命名方法,并在可用时执行它。

不要直接调用此方法,因为它是一个 PHP 魔术方法,当调用未知方法时将隐式调用。

public mixed __call ( $name, $params )
$name 字符串

方法名称

$params 数组

方法参数

return mixed

方法返回值

throws yii\base\UnknownMethodException

调用未知方法时

                public function __call($name, $params)
{
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $object) {
        if ($object->hasMethod($name)) {
            return call_user_func_array([$object, $name], $params);
        }
    }
    throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}

            
__clone() 公共方法

此方法在通过克隆现有对象创建对象后被调用。

它删除所有行为,因为它们附加到旧对象。

public void __clone ( )

                public function __clone()
{
    parent::__clone();
    $this->_errors = null;
    $this->_validators = null;
}

            
__construct() 公共方法

定义于: yii\base\BaseObject::__construct()

构造函数。

默认实现做两件事

  • 使用给定的配置 $config 初始化对象。
  • 调用 init()

如果此方法在子类中被重写,则建议

  • 构造函数的最后一个参数是一个配置数组,如这里的 $config
  • 在构造函数的末尾调用父实现。
public void __construct ( $config = [] )
$config 数组

将用于初始化对象属性的名称-值对

                public function __construct($config = [])
{
    if (!empty($config)) {
        Yii::configure($this, $config);
    }
    $this->init();
}

            
__get() 公共方法

定义于: yii\base\Component::__get()

返回组件属性的值。

此方法将按以下顺序检查并采取相应措施

  • 由 getter 定义的属性:返回 getter 结果
  • 行为的属性:返回行为属性值

不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 $value = $component->property; 时会隐式调用。

另请参阅 __set()

public mixed __get ( $name )
$name 字符串

属性名称

return mixed

属性值或行为属性的值

throws yii\base\UnknownPropertyException

如果属性未定义

throws yii\base\InvalidCallException

如果属性是只写的。

                public function __get($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        // read property, e.g. getName()
        return $this->$getter();
    }
    // behavior property
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $behavior) {
        if ($behavior->canGetProperty($name)) {
            return $behavior->$name;
        }
    }
    if (method_exists($this, 'set' . $name)) {
        throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
    }
    throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
}

            
__isset() public method

定义于: yii\base\Component::__isset()

检查属性是否已设置,即定义且不为空。

此方法将按以下顺序检查并采取相应措施

  • 由 setter 定义的属性:返回属性是否已设置
  • 行为的属性:返回属性是否已设置
  • 对于不存在的属性,返回 false

不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 isset($component->property) 时会隐式调用。

另请参阅 https://php.ac.cn/manual/en/function.isset.php

public boolean __isset ( $name )
$name 字符串

属性名称或事件名称

return boolean

命名的属性是否已设置

                public function __isset($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        return $this->$getter() !== null;
    }
    // behavior property
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $behavior) {
        if ($behavior->canGetProperty($name)) {
            return $behavior->$name !== null;
        }
    }
    return false;
}

            
__set() public method

定义于: yii\base\Component::__set()

设置组件属性的值。

此方法将按以下顺序检查并采取相应措施

  • 由 setter 定义的属性:设置属性值
  • 以“on xyz”格式的事件:将处理程序附加到事件“xyz”
  • 以“as xyz”格式的行为:附加名为“xyz”的行为
  • 行为的属性:设置行为属性值

不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 $component->property = $value; 时会隐式调用。

另请参阅 __get()

public void __set ( $name, $value )
$name 字符串

属性名称或事件名称

$value mixed

属性值

throws yii\base\UnknownPropertyException

如果属性未定义

throws yii\base\InvalidCallException

如果属性是只读的。

                public function __set($name, $value)
{
    $setter = 'set' . $name;
    if (method_exists($this, $setter)) {
        // set property
        $this->$setter($value);
        return;
    } elseif (strncmp($name, 'on ', 3) === 0) {
        // on event: attach event handler
        $this->on(trim(substr($name, 3)), $value);
        return;
    } elseif (strncmp($name, 'as ', 3) === 0) {
        // as behavior: attach behavior
        $name = trim(substr($name, 3));
        $this->attachBehavior($name, $value instanceof Behavior ? $value : Yii::createObject($value));
        return;
    }
    // behavior property
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $behavior) {
        if ($behavior->canSetProperty($name)) {
            $behavior->$name = $value;
            return;
        }
    }
    if (method_exists($this, 'get' . $name)) {
        throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
    }
    throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
}

            
__unset() public method

定义于: yii\base\Component::__unset()

将组件属性设置为 null。

此方法将按以下顺序检查并采取相应措施

  • 由 setter 定义的属性:将属性值设置为 null
  • 行为的属性:将属性值设置为 null

不要直接调用此方法,因为它是一个 PHP 魔术方法,在执行 unset($component->property) 时会隐式调用。

另请参阅 https://php.ac.cn/manual/en/function.unset.php

public void __unset ( $name )
$name 字符串

属性名称

throws yii\base\InvalidCallException

如果属性是只读的。

                public function __unset($name)
{
    $setter = 'set' . $name;
    if (method_exists($this, $setter)) {
        $this->$setter(null);
        return;
    }
    // behavior property
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $behavior) {
        if ($behavior->canSetProperty($name)) {
            $behavior->$name = null;
            return;
        }
    }
    throw new InvalidCallException('Unsetting an unknown or read-only property: ' . get_class($this) . '::' . $name);
}

            
activeAttributes() public method

返回当前场景中受验证影响的属性名称列表。

public string[] activeAttributes ( )
return 字符串[]

安全属性名称

                public function activeAttributes()
{
    $scenario = $this->getScenario();
    $scenarios = $this->scenarios();
    if (!isset($scenarios[$scenario])) {
        return [];
    }
    $attributes = array_keys(array_flip($scenarios[$scenario]));
    foreach ($attributes as $i => $attribute) {
        if (strncmp($attribute, '!', 1) === 0) {
            $attributes[$i] = substr($attribute, 1);
        }
    }
    return $attributes;
}

            
addError() public method

将新错误添加到指定属性。

public void addError ( $attribute, $error '' )
$attribute 字符串

属性名称

$error 字符串

新的错误消息

                public function addError($attribute, $error = '')
{
    $this->_errors[$attribute][] = $error;
}

            
addErrors() public method (available since version 2.0.2)

添加错误列表。

public void addErrors ( array $items )
$items 数组

错误列表。数组键必须是属性名称。数组值应该是错误消息。如果一个属性有多个错误,这些错误必须用数组的形式给出。你可以使用 getErrors() 的结果作为此参数的值。

                public function addErrors(array $items)
{
    foreach ($items as $attribute => $errors) {
        if (is_array($errors)) {
            foreach ($errors as $error) {
                $this->addError($attribute, $error);
            }
        } else {
            $this->addError($attribute, $errors);
        }
    }
}

            
afterValidate() public method

此方法在验证结束后被调用。

默认实现会引发一个 afterValidate 事件。你可以重写此方法来在验证后进行后处理。确保调用父实现,以便可以引发事件。

public void afterValidate ( )

                public function afterValidate()
{
    $this->trigger(self::EVENT_AFTER_VALIDATE);
}

            
attachBehavior() public method

定义于: yii\base\Component::attachBehavior()

将行为附加到此组件。

此方法将根据给定的配置创建行为对象。之后,行为对象将通过调用 yii\base\Behavior::attach() 方法附加到此组件。

另请参阅 detachBehavior()

public yii\base\Behavior attachBehavior ( $name, $behavior )
$name 字符串

行为的名称。

$behavior string|array|yii\base\Behavior

行为配置。可以是以下之一

return yii\base\Behavior

行为对象

                public function attachBehavior($name, $behavior)
{
    $this->ensureBehaviors();
    return $this->attachBehaviorInternal($name, $behavior);
}

            
attachBehaviors() public method

定义于: yii\base\Component::attachBehaviors()

将行为列表附加到组件。

每个行为都由其名称索引,并且应该是一个 yii\base\Behavior 对象,一个指定行为类的字符串,或者一个用于创建行为的配置数组。

另请参阅 attachBehavior()

public void attachBehaviors ( $behaviors )
$behaviors 数组

要附加到组件的行为列表

                public function attachBehaviors($behaviors)
{
    $this->ensureBehaviors();
    foreach ($behaviors as $name => $behavior) {
        $this->attachBehaviorInternal($name, $behavior);
    }
}

            
attributeHints() public method (available since version 2.0.4)

返回属性提示。

属性提示主要用于显示目的。例如,给定一个属性 isPublic,我们可以声明一个提示 Whether the post should be visible for not logged in users,它提供了对属性含义的用户友好描述,并且可以显示给最终用户。

与标签不同,如果省略显式声明,则不会生成提示。

注意,为了继承父类中定义的提示,子类需要使用 array_merge() 等函数将父提示与子提示合并。

public array attributeHints ( )
return 数组

属性提示(名称 => 提示)

                public function attributeHints()
{
    return [];
}

            
attributeLabels() 公共方法

返回属性标签。

属性标签主要用于显示目的。例如,给定一个属性 firstName,我们可以声明一个标签 First Name,它更友好,可以显示给最终用户。

默认情况下,属性标签使用 generateAttributeLabel() 生成。此方法允许您显式指定属性标签。

注意,为了继承父类中定义的标签,子类需要使用诸如 array_merge() 之类的函数将父标签与子标签合并。

另请参阅 generateAttributeLabel().

public array attributeLabels ( )
return 数组

属性标签(名称 => 标签)

                public function attributeLabels()
{
    return [];
}

            
attributes() 公共方法

返回属性名称列表。

默认情况下,此方法返回类中所有公共的非静态属性。您可以重写此方法来更改默认行为。

public string[] attributes ( )
return 字符串[]

属性名称列表。

                public function attributes()
{
    $class = new ReflectionClass($this);
    $names = [];
    foreach ($class->getProperties(\ReflectionProperty::IS_PUBLIC) as $property) {
        if (!$property->isStatic()) {
            $names[] = $property->getName();
        }
    }
    return $names;
}

            
beforeValidate() 公共方法

此方法在验证开始之前被调用。

默认实现引发 beforeValidate 事件。您可以重写此方法来在验证之前进行初步检查。确保调用父实现,以便可以引发事件。

public boolean beforeValidate ( )
return boolean

是否应执行验证。默认为 true。如果返回 false,验证将停止,模型被视为无效。

                public function beforeValidate()
{
    $event = new ModelEvent();
    $this->trigger(self::EVENT_BEFORE_VALIDATE, $event);
    return $event->isValid;
}

            
behaviors() 公共方法

定义于: yii\base\Component::behaviors()

返回此组件应表现为的行为列表。

子类可以重写此方法来指定它们要表现的行为。

此方法的返回值应该是一个行为对象或配置的数组,按行为名称索引。行为配置可以是指定行为类的字符串,也可以是以下结构的数组

'behaviorName' => [
    'class' => 'BehaviorClass',
    'property1' => 'value1',
    'property2' => 'value2',
]

请注意,行为类必须扩展自 yii\base\Behavior。行为可以使用名称或匿名方式附加。当使用名称作为数组键时,使用此名称,行为可以在以后使用 getBehavior() 检索,或使用 detachBehavior() 分离。匿名行为无法检索或分离。

在此方法中声明的行为将自动附加到组件(按需)。

public array behaviors ( )
return 数组

行为配置。

                public function behaviors()
{
    return [];
}

            
canGetProperty() 公共方法

定义于: yii\base\Component::canGetProperty()

返回一个值,指示是否可以读取属性。

如果可以读取属性,则

  • 类具有与指定名称关联的 getter 方法(在这种情况下,属性名称不区分大小写);
  • 类具有指定名称的成员变量(当 $checkVars 为 true 时);
  • 附加的行为具有给定名称的可读属性(当 $checkBehaviors 为 true 时)。

另请参阅 canSetProperty().

public boolean canGetProperty ( $name, $checkVars true, $checkBehaviors true )
$name 字符串

属性名称

$checkVars boolean

是否将成员变量视为属性

$checkBehaviors boolean

是否将行为的属性视为此组件的属性

return boolean

属性是否可读

                public function canGetProperty($name, $checkVars = true, $checkBehaviors = true)
{
    if (method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name)) {
        return true;
    } elseif ($checkBehaviors) {
        $this->ensureBehaviors();
        foreach ($this->_behaviors as $behavior) {
            if ($behavior->canGetProperty($name, $checkVars)) {
                return true;
            }
        }
    }
    return false;
}

            
canSetProperty() 公共方法

定义于: yii\base\Component::canSetProperty()

返回一个值,指示是否可以设置属性。

如果可以写入属性,则

  • 类具有与指定名称关联的 setter 方法(在这种情况下,属性名称不区分大小写);
  • 类具有指定名称的成员变量(当 $checkVars 为 true 时);
  • 附加的行为具有给定名称的可写属性(当 $checkBehaviors 为 true 时)。

另请参阅 canGetProperty().

public boolean canSetProperty ( $name, $checkVars true, $checkBehaviors true )
$name 字符串

属性名称

$checkVars boolean

是否将成员变量视为属性

$checkBehaviors boolean

是否将行为的属性视为此组件的属性

return boolean

属性是否可写

                public function canSetProperty($name, $checkVars = true, $checkBehaviors = true)
{
    if (method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name)) {
        return true;
    } elseif ($checkBehaviors) {
        $this->ensureBehaviors();
        foreach ($this->_behaviors as $behavior) {
            if ($behavior->canSetProperty($name, $checkVars)) {
                return true;
            }
        }
    }
    return false;
}

            
className() 公共静态方法
自 2.0.14 起已弃用。在 PHP >=5.5 上,使用 ::class 代替。

定义于: yii\base\BaseObject::className()

返回此类的完全限定名称。

public static string className ( )
return 字符串

此类的完全限定名称。

                public static function className()
{
    return get_called_class();
}

            
clearErrors() 公共方法

删除所有属性或单个属性的错误。

public void clearErrors ( $attribute null )
$attribute string|null

属性名称。使用 null 来删除所有属性的错误。

                public function clearErrors($attribute = null)
{
    if ($attribute === null) {
        $this->_errors = [];
    } else {
        unset($this->_errors[$attribute]);
    }
}

            
createValidators() 公共方法

根据 rules() 中指定的验证规则创建验证器对象。

getValidators() 不同,每次调用此方法时,都会返回一个新的验证器列表。

public ArrayObject createValidators ( )
return ArrayObject

验证器

throws yii\base\InvalidConfigException

如果任何验证规则配置无效

                public function createValidators()
{
    $validators = new ArrayObject();
    foreach ($this->rules() as $rule) {
        if ($rule instanceof Validator) {
            $validators->append($rule);
        } elseif (is_array($rule) && isset($rule[0], $rule[1])) { // attributes, validator type
            $validator = Validator::createValidator($rule[1], $this, (array) $rule[0], array_slice($rule, 2));
            $validators->append($validator);
        } else {
            throw new InvalidConfigException('Invalid validation rule: a rule must specify both attribute names and validator type.');
        }
    }
    return $validators;
}

            
detachBehavior() 公共方法

定义于: yii\base\Component::detachBehavior()

从组件中分离行为。

将调用行为的 yii\base\Behavior::detach() 方法。

public yii\base\Behavior|null detachBehavior ( $name )
$name 字符串

行为的名称。

return yii\base\Behavior|null

分离的行为。如果行为不存在,则为 Null。

                public function detachBehavior($name)
{
    $this->ensureBehaviors();
    if (isset($this->_behaviors[$name])) {
        $behavior = $this->_behaviors[$name];
        unset($this->_behaviors[$name]);
        $behavior->detach();
        return $behavior;
    }
    return null;
}

            
detachBehaviors() 公共方法

定义于: yii\base\Component::detachBehaviors()

从组件中分离所有行为。

public void detachBehaviors ( )

                public function detachBehaviors()
{
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $name => $behavior) {
        $this->detachBehavior($name);
    }
}

            
ensureBehaviors() 公共方法

定义于: yii\base\Component::ensureBehaviors()

确保 behaviors() 中声明的行为已附加到此组件。

public void ensureBehaviors ( )

                public function ensureBehaviors()
{
    if ($this->_behaviors === null) {
        $this->_behaviors = [];
        foreach ($this->behaviors() as $name => $behavior) {
            $this->attachBehaviorInternal($name, $behavior);
        }
    }
}

            
extraFields() 公共方法

定义于: yii\base\ArrayableTrait::extraFields()

返回可进一步扩展的字段列表,并由 toArray() 返回。

此方法类似于 fields(),不同之处在于,此方法返回的字段列表不会默认由 toArray() 返回。 只有在调用 toArray() 时显式指定要扩展的字段名时,才会导出其值。

默认实现返回一个空数组。

您可以覆盖此方法以根据一些上下文信息(例如当前应用程序用户)返回一个可扩展字段列表。

另请参阅

public array extraFields ( )
return 数组

可扩展字段名或字段定义的列表。 请参考 fields() 了解返回值的格式。

                public function extraFields()
{
    return [];
}

            
extractFieldsFor() 受保护方法 (自版本 2.0.14 起可用)

定义于: yii\base\ArrayableTrait::extractFieldsFor()

从给定根字段的字段集合中提取嵌套字段。嵌套字段用点 (.) 分隔。例如:"item.id" 上面的示例将提取 "id"。

protected array extractFieldsFor ( array $fields, $rootField )
$fields 数组

用于提取的字段

$rootField 字符串

我们想要提取嵌套字段的根字段

return 数组

为给定字段提取的嵌套字段

                protected function extractFieldsFor(array $fields, $rootField)
{
    $result = [];
    foreach ($fields as $field) {
        if (0 === strpos($field, "{$rootField}.")) {
            $result[] = preg_replace('/^' . preg_quote($rootField, '/') . '\./i', '', $field);
        }
    }
    return array_unique($result);
}

            
extractRootFields() 受保护方法 (自版本 2.0.14 起可用)

定义于: yii\base\ArrayableTrait::extractRootFields()

从嵌套字段中提取根字段名称。

嵌套字段用点 (.) 分隔。 例如:“item.id” 上面的示例将提取“item”。

protected array extractRootFields ( array $fields )
$fields 数组

用于提取的字段

return 数组

从给定嵌套字段中提取的根字段

                protected function extractRootFields(array $fields)
{
    $result = [];
    foreach ($fields as $field) {
        $result[] = current(explode('.', $field, 2));
    }
    if (in_array('*', $result, true)) {
        $result = [];
    }
    return array_unique($result);
}

            
fields() 公共方法

返回应由 toArray() 在未指定特定字段时默认返回的字段列表。

字段是 toArray() 返回的数组中的命名元素。

此方法应返回一个字段名或字段定义的数组。 如果是前者,字段名将被视为一个对象属性名,其值将用作字段值。 如果是后者,数组键应该是字段名,而数组值应该是相应的字段定义,它可以是对象属性名或返回相应字段值的 PHP 可调用对象。 可调用对象的签名应该是

function ($model, $field) {
    // return field value
}

例如,以下代码声明了四个字段

  • email: 字段名与属性名 email 相同;
  • firstNamelastName: 字段名是 firstNamelastName,它们的值从 first_namelast_name 属性获得;
  • fullName: 字段名是 fullName。 其值通过连接 first_namelast_name 获得。
return [
    'email',
    'firstName' => 'first_name',
    'lastName' => 'last_name',
    'fullName' => function ($model) {
        return $model->first_name . ' ' . $model->last_name;
    },
];

在此方法中,您可能还想根据一些上下文信息返回不同的字段列表。 例如,根据 $scenario 或当前应用程序用户的权限,您可以返回不同的可见字段集或过滤掉一些字段。

此方法的默认实现返回由相同属性名称索引的 attributes()

另请参阅 toArray()

public array fields ( )
return 数组

字段名或字段定义的列表。

                public function fields()
{
    $fields = $this->attributes();
    return array_combine($fields, $fields);
}

            
formName() 公共方法

返回此模型类应使用的表单名称。

表单名称主要由 yii\widgets\ActiveForm 用于确定如何命名模型中属性的输入字段。 如果表单名称为“A”,属性名为“b”,则相应的输入名称将为“A[b]”。 如果表单名称为空字符串,则输入名称将为“b”。

上述命名方案的目的是,对于包含多个不同模型的表单,每个模型的属性都分组在 POST 数据的子数组中,这样更容易区分它们。

默认情况下,此方法返回模型类名(不包含命名空间部分)作为表单名称。 当模型在不同的表单中使用时,您可以覆盖它。

另请参阅 load()

public string formName ( )
return 字符串

此模型类的表单名称。

throws yii\base\InvalidConfigException

当表单使用匿名类定义并且没有覆盖 formName() 方法时。

                public function formName()
{
    $reflector = new ReflectionClass($this);
    if (PHP_VERSION_ID >= 70000 && $reflector->isAnonymous()) {
        throw new InvalidConfigException('The "formName()" method should be explicitly defined for anonymous models');
    }
    return $reflector->getShortName();
}

            
generateAttributeLabel() 公共方法

根据给定的属性名称生成用户友好的属性标签。

这是通过用空格替换下划线、破折号和点,并将每个单词的第一个字母更改为大写来完成的。 例如,“department_name” 或“DepartmentName” 将生成“Department Name”。

public string generateAttributeLabel ( $name )
$name 字符串

列名

return 字符串

属性标签

                public function generateAttributeLabel($name)
{
    return Inflector::camel2words($name, true);
}

            
getActiveValidators() 公共方法

返回适用于当前 $scenario 的验证器。

public yii\validators\Validator[] getActiveValidators ( $attribute null )
$attribute string|null

应返回其适用验证器的属性的名称。 如果这是 null,则将返回模型中所有属性的验证器。

return yii\validators\Validator[]

适用于当前 $scenario 的验证器。

                public function getActiveValidators($attribute = null)
{
    $activeAttributes = $this->activeAttributes();
    if ($attribute !== null && !in_array($attribute, $activeAttributes, true)) {
        return [];
    }
    $scenario = $this->getScenario();
    $validators = [];
    foreach ($this->getValidators() as $validator) {
        if ($attribute === null) {
            $validatorAttributes = $validator->getValidationAttributes($activeAttributes);
            $attributeValid = !empty($validatorAttributes);
        } else {
            $attributeValid = in_array($attribute, $validator->getValidationAttributes($attribute), true);
        }
        if ($attributeValid && $validator->isActive($scenario)) {
            $validators[] = $validator;
        }
    }
    return $validators;
}

            
getAttributeHint() 公共方法 (自版本 2.0.4 起可用)

返回指定属性的文本提示。

另请参见 attributeHints()

public string getAttributeHint ( $attribute )
$attribute 字符串

属性名称

return 字符串

属性提示

                public function getAttributeHint($attribute)
{
    $hints = $this->attributeHints();
    return isset($hints[$attribute]) ? $hints[$attribute] : '';
}

            
getAttributeLabel() 公共方法

返回指定属性的文本标签。

另请参阅

public string getAttributeLabel ( $attribute )
$attribute 字符串

属性名称

return 字符串

属性标签

                public function getAttributeLabel($attribute)
{
    $labels = $this->attributeLabels();
    return isset($labels[$attribute]) ? $labels[$attribute] : $this->generateAttributeLabel($attribute);
}

            
getAttributes() 公共方法

返回属性值。

public array getAttributes ( $names null, $except = [] )
$names array|null

需要返回其值的属性列表。默认为 null,表示将返回 attributes() 中列出的所有属性。如果它是一个数组,则只返回数组中的属性。

$except 数组

不应返回其值的属性列表。

return 数组

属性值(名称 => 值)。

                public function getAttributes($names = null, $except = [])
{
    $values = [];
    if ($names === null) {
        $names = $this->attributes();
    }
    foreach ($names as $name) {
        $values[$name] = $this->$name;
    }
    foreach ($except as $name) {
        unset($values[$name]);
    }
    return $values;
}

            
getBehavior() 公共方法

定义于: yii\base\Component::getBehavior()

返回命名行为对象。

public yii\base\Behavior|null getBehavior ( $name )
$name 字符串

行为名称

return yii\base\Behavior|null

行为对象,如果行为不存在则为 null

                public function getBehavior($name)
{
    $this->ensureBehaviors();
    return isset($this->_behaviors[$name]) ? $this->_behaviors[$name] : null;
}

            
getBehaviors() 公共方法

定义于: yii\base\Component::getBehaviors()

返回附加到此组件的所有行为。

public yii\base\Behavior[] getBehaviors ( )
return yii\base\Behavior[]

附加到此组件的行为列表

                public function getBehaviors()
{
    $this->ensureBehaviors();
    return $this->_behaviors;
}

            
getErrorSummary() 公共方法 (从版本 2.0.14 开始可用)

将所有属性的错误作为一维数组返回。

另请参阅

public array getErrorSummary ( $showAllErrors )
$showAllErrors boolean

布尔值,如果设置为 true,则将显示每个属性的每个错误消息,否则只显示每个属性的第一个错误消息。

return 数组

所有属性的错误,作为一个一维数组。如果无错误,则返回空数组。

                public function getErrorSummary($showAllErrors)
{
    $lines = [];
    $errors = $showAllErrors ? $this->getErrors() : $this->getFirstErrors();
    foreach ($errors as $es) {
        $lines = array_merge($lines, (array)$es);
    }
    return $lines;
}

            
getErrors() 公共方法

返回所有属性或单个属性的错误。

另请参阅

public array getErrors ( $attribute null )
$attribute string|null

属性名称。使用 null 获取所有属性的错误。

return 数组

所有属性或指定属性的错误。如果无错误,则返回空数组。有关详细信息,请参阅 getErrors()。请注意,当返回所有属性的错误时,结果是一个二维数组,如下所示

[
    'username' => [
        'Username is required.',
        'Username must contain only word characters.',
    ],
    'email' => [
        'Email address is invalid.',
    ]
]

                public function getErrors($attribute = null)
{
    if ($attribute === null) {
        return $this->_errors === null ? [] : $this->_errors;
    }
    return isset($this->_errors[$attribute]) ? $this->_errors[$attribute] : [];
}

            
getFirstError() 公共方法

返回指定属性的第一个错误。

另请参阅

public string|null getFirstError ( $attribute )
$attribute 字符串

属性名称。

return string|null

错误消息。如果无错误,则返回 null。

                public function getFirstError($attribute)
{
    return isset($this->_errors[$attribute]) ? reset($this->_errors[$attribute]) : null;
}

            
getFirstErrors() 公共方法

返回模型中每个属性的第一个错误。

另请参阅

public array getFirstErrors ( )
return 数组

第一个错误。数组键是属性名称,数组值是相应的错误消息。如果无错误,则返回空数组。

                public function getFirstErrors()
{
    if (empty($this->_errors)) {
        return [];
    }
    $errors = [];
    foreach ($this->_errors as $name => $es) {
        if (!empty($es)) {
            $errors[$name] = reset($es);
        }
    }
    return $errors;
}

            
getIterator() 公共方法

返回用于遍历模型中属性的迭代器。

此方法是接口 IteratorAggregate 所需的。

public ArrayIterator getIterator ( )
return ArrayIterator

用于遍历列表中项目的迭代器。

                #[\ReturnTypeWillChange]
public function getIterator()
{
    $attributes = $this->getAttributes();
    return new ArrayIterator($attributes);
}

            
getScenario() 公共方法

返回此模型所使用的场景。

场景影响验证的执行方式以及哪些属性可以进行批量赋值。

public string getScenario ( )
return 字符串

此模型所处的场景。默认为 SCENARIO_DEFAULT

                public function getScenario()
{
    return $this->_scenario;
}

            
getValidators() 公共方法

返回 rules() 中声明的所有验证器。

此方法与 getActiveValidators() 的区别在于,后者只返回适用于当前 $scenario 的验证器。

因为此方法返回一个 ArrayObject 对象,所以你可以通过插入或删除验证器来操作它(在模型行为中很有用)。例如,

$model->validators[] = $newValidator;
public ArrayObject|yii\validators\Validator[] getValidators ( )
return ArrayObject|yii\validators\Validator[]

模型中声明的所有验证器。

                public function getValidators()
{
    if ($this->_validators === null) {
        $this->_validators = $this->createValidators();
    }
    return $this->_validators;
}

            
hasErrors() 公共方法

返回一个值,指示是否存在任何验证错误。

public boolean hasErrors ( $attribute null )
$attribute string|null

属性名称。使用 null 检查所有属性。

return boolean

是否存在任何错误。

                public function hasErrors($attribute = null)
{
    return $attribute === null ? !empty($this->_errors) : isset($this->_errors[$attribute]);
}

            
hasEventHandlers() 公共方法

定义于: yii\base\Component::hasEventHandlers()

返回一个值,指示是否将任何处理程序附加到命名事件。

public boolean hasEventHandlers ( $name )
$name 字符串

事件名称

return boolean

事件是否附加了任何处理程序。

                public function hasEventHandlers($name)
{
    $this->ensureBehaviors();
    if (!empty($this->_events[$name])) {
        return true;
    }
    foreach ($this->_eventWildcards as $wildcard => $handlers) {
        if (!empty($handlers) && StringHelper::matchWildcard($wildcard, $name)) {
            return true;
        }
    }
    return Event::hasHandlers($this, $name);
}

            
hasMethod() 公共方法

定义于: yii\base\Component::hasMethod()

返回一个值,指示是否定义了方法。

如果满足以下条件,则定义了方法:

  • 类具有指定名称的方法
  • 附加的行为具有指定名称的方法(当 $checkBehaviors 为 true 时)。
public boolean hasMethod ( $name, $checkBehaviors true )
$name 字符串

属性名称

$checkBehaviors boolean

是否将行为的方法视为该组件的方法

return boolean

该方法是否已定义

                public function hasMethod($name, $checkBehaviors = true)
{
    if (method_exists($this, $name)) {
        return true;
    } elseif ($checkBehaviors) {
        $this->ensureBehaviors();
        foreach ($this->_behaviors as $behavior) {
            if ($behavior->hasMethod($name)) {
                return true;
            }
        }
    }
    return false;
}

            
hasProperty() 公共方法

定义于: yii\base\Component::hasProperty()

返回一个值,指示是否为此组件定义了属性。

如果满足以下条件,则定义了属性:

  • 类具有与指定名称关联的 getter 或 setter 方法(在这种情况下,属性名称不区分大小写);
  • 类具有指定名称的成员变量(当 $checkVars 为 true 时);
  • 附加的行为具有指定名称的属性(当 $checkBehaviors 为 true 时)。

另请参阅

public boolean hasProperty ( $name, $checkVars true, $checkBehaviors true )
$name 字符串

属性名称

$checkVars boolean

是否将成员变量视为属性

$checkBehaviors boolean

是否将行为的属性视为此组件的属性

return boolean

该属性是否已定义

                public function hasProperty($name, $checkVars = true, $checkBehaviors = true)
{
    return $this->canGetProperty($name, $checkVars, $checkBehaviors) || $this->canSetProperty($name, false, $checkBehaviors);
}

            
init() 公共方法

定义于: yii\base\BaseObject::init()

初始化对象。

该方法在构造函数结束时调用,在对象使用给定的配置初始化之后。

public void init ( )

                public function init()
{
}

            
instance() 公共静态方法

定义于: yii\base\StaticInstanceTrait::instance()

返回静态类实例,可用于获取元信息。

public static static instance ( $refresh false )
$refresh boolean

是否即使静态实例已缓存也要重新创建。

return yii\base\Model

类实例。

                public static function instance($refresh = false)
{
    $className = get_called_class();
    if ($refresh || !isset(self::$_instances[$className])) {
        self::$_instances[$className] = Yii::createObject($className);
    }
    return self::$_instances[$className];
}

            
isAttributeActive() 公共方法

返回一个值,指示属性在当前场景中是否处于活动状态。

另请参见 activeAttributes()

public boolean isAttributeActive ( $attribute )
$attribute 字符串

属性名称

return boolean

该属性在当前场景中是否处于活动状态

                public function isAttributeActive($attribute)
{
    return in_array($attribute, $this->activeAttributes(), true);
}

            
isAttributeRequired() 公共方法

返回一个值,指示属性是否必需。

这可以通过检查属性是否在当前 $scenario 中与 required 验证规则关联来确定。

请注意,当验证器使用 $when 应用条件验证时,此方法将返回 false,无论 when 条件如何,因为它可能在模型使用数据加载之前被调用。

public boolean isAttributeRequired ( $attribute )
$attribute 字符串

属性名称

return boolean

该属性是否必需

                public function isAttributeRequired($attribute)
{
    foreach ($this->getActiveValidators($attribute) as $validator) {
        if ($validator instanceof RequiredValidator && $validator->when === null) {
            return true;
        }
    }
    return false;
}

            
isAttributeSafe() 公共方法

返回一个值,指示属性是否可以进行批量赋值。

另请参见 safeAttributes()

public boolean isAttributeSafe ( $attribute )
$attribute 字符串

属性名称

return boolean

该属性是否安全用于批量赋值

                public function isAttributeSafe($attribute)
{
    return in_array($attribute, $this->safeAttributes(), true);
}

            
load() 公共方法

使用输入数据填充模型。

此方法提供了一个方便的快捷方式,用于

if (isset($_POST['FormName'])) {
    $model->attributes = $_POST['FormName'];
    if ($model->save()) {
        // handle success
    }
}

可以使用 load() 写成

if ($model->load($_POST) && $model->save()) {
    // handle success
}

load() 从模型的 formName() 方法(您可以覆盖此方法)获取 'FormName',除非指定了 $formName 参数。如果表单名称为空,则 load() 使用整个 $data 来填充模型,而不是 $data['FormName']

请注意,要填充的数据会受到 setAttributes() 进行的安全检查。

public boolean load ( $data, $formName null )
$data 数组

要加载的数据数组,通常是 $_POST$_GET

$formName string|null

用于将数据加载到模型中的表单名称,表单未使用时为空字符串。如果未设置,将使用 formName()

return boolean

load() 是否在 $data 中找到了预期的表单。

                public function load($data, $formName = null)
{
    $scope = $formName === null ? $this->formName() : $formName;
    if ($scope === '' && !empty($data)) {
        $this->setAttributes($data);
        return true;
    } elseif (isset($data[$scope])) {
        $this->setAttributes($data[$scope]);
        return true;
    }
    return false;
}

            
loadMultiple() 公共静态方法

使用来自最终用户的数据填充一组模型。

此方法主要用于收集表格数据输入。要为每个模型加载的数据是 $data[formName][index],其中 formName 指的是 formName() 的值,而 index$models 数组中模型的索引。如果 formName() 为空,则 $data[index] 将用于填充每个模型。要填充到每个模型中的数据会受到 setAttributes() 进行的安全检查。

public static boolean loadMultiple ( $models, $data, $formName null )
$models 数组

要填充的模型。请注意,所有模型都应该具有相同的类。

$data 数组

数据数组。这通常是 $_POST$_GET,但也可能是最终用户提供的任何有效数组。

$formName string|null

用于将数据加载到模型中的表单名称。如果未设置,它将使用 $models 中第一个模型的 formName() 值。此参数自版本 2.0.1 起可用。

return boolean

至少一个模型是否成功填充。

                public static function loadMultiple($models, $data, $formName = null)
{
    if ($formName === null) {
        /* @var $first Model|false */
        $first = reset($models);
        if ($first === false) {
            return false;
        }
        $formName = $first->formName();
    }
    $success = false;
    foreach ($models as $i => $model) {
        /* @var $model Model */
        if ($formName == '') {
            if (!empty($data[$i]) && $model->load($data[$i], '')) {
                $success = true;
            }
        } elseif (!empty($data[$formName][$i]) && $model->load($data[$formName][$i], '')) {
            $success = true;
        }
    }
    return $success;
}

            
off() 公共方法

定义于: yii\base\Component::off()

从此组件中分离现有的事件处理程序。

此方法与 on() 相反。

注意:如果为事件名称传递通配符模式,则仅会删除使用此通配符注册的处理程序,而使用与该通配符匹配的普通名称注册的处理程序将保留。

另请参见 on()

public boolean off ( $name, $handler null )
$name 字符串

事件名称

$handler callable|null

要移除的事件处理程序。如果它为空,则将移除附加到命名事件的所有处理程序。

return boolean

如果找到并分离了处理程序

                public function off($name, $handler = null)
{
    $this->ensureBehaviors();
    if (empty($this->_events[$name]) && empty($this->_eventWildcards[$name])) {
        return false;
    }
    if ($handler === null) {
        unset($this->_events[$name], $this->_eventWildcards[$name]);
        return true;
    }
    $removed = false;
    // plain event names
    if (isset($this->_events[$name])) {
        foreach ($this->_events[$name] as $i => $event) {
            if ($event[0] === $handler) {
                unset($this->_events[$name][$i]);
                $removed = true;
            }
        }
        if ($removed) {
            $this->_events[$name] = array_values($this->_events[$name]);
            return true;
        }
    }
    // wildcard event names
    if (isset($this->_eventWildcards[$name])) {
        foreach ($this->_eventWildcards[$name] as $i => $event) {
            if ($event[0] === $handler) {
                unset($this->_eventWildcards[$name][$i]);
                $removed = true;
            }
        }
        if ($removed) {
            $this->_eventWildcards[$name] = array_values($this->_eventWildcards[$name]);
            // remove empty wildcards to save future redundant regex checks:
            if (empty($this->_eventWildcards[$name])) {
                unset($this->_eventWildcards[$name]);
            }
        }
    }
    return $removed;
}

            
offsetExists() 公共方法

返回指定偏移量处是否存在元素。

此方法是 SPL 接口 ArrayAccess 所必需的。当您使用类似 isset($model[$offset]) 的内容时,会隐式调用它。

public boolean offsetExists ( $offset )
$offset 字符串

要检查的偏移量。

return boolean

是否存在偏移量。

                #[\ReturnTypeWillChange]
public function offsetExists($offset)
{
    return isset($this->$offset);
}

            
offsetGet() 公共方法

返回指定偏移量处的元素。

此方法是 SPL 接口 ArrayAccess 所必需的。当您使用类似 $value = $model[$offset]; 的内容时,会隐式调用它。

public mixed offsetGet ( $offset )
$offset 字符串

要检索元素的偏移量。

return mixed

偏移量处的元素,如果在偏移量处未找到元素,则为 null

                #[\ReturnTypeWillChange]
public function offsetGet($offset)
{
    return $this->$offset;
}

            
offsetSet() 公共方法

设置指定偏移处的元素。

此方法是 SPL 接口 ArrayAccess 所必需的。当您使用类似 $model[$offset] = $value; 的内容时,会隐式调用它。

public void offsetSet ( $offset, $value )
$offset 字符串

要设置元素的偏移量

$value mixed

元素值

                #[\ReturnTypeWillChange]
public function offsetSet($offset, $value)
{
    $this->$offset = $value;
}

            
offsetUnset() 公共方法

将指定偏移处的元素值设置为 null。

此方法是 SPL 接口 ArrayAccess 所必需的。当您使用类似 unset($model[$offset]) 的内容时,会隐式调用它。

public void offsetUnset ( $offset )
$offset 字符串

要取消设置元素的偏移量

                #[\ReturnTypeWillChange]
public function offsetUnset($offset)
{
    $this->$offset = null;
}

            
on() 公共方法

定义于: yii\base\Component::on()

将事件处理程序附加到事件。

事件处理程序必须是有效的 PHP 回调。以下是一些示例

function ($event) { ... }         // anonymous function
[$object, 'handleClick']          // $object->handleClick()
['Page', 'handleClick']           // Page::handleClick()
'handleClick'                     // global function handleClick()

事件处理程序必须以以下签名定义,

function ($event)

其中 $event 是一个 yii\base\Event 对象,其中包含与事件相关的参数。

从 2.0.14 开始,您可以将事件名称指定为通配符模式

$component->on('event.group.*', function ($event) {
    Yii::trace($event->name . ' is triggered.');
});

另请参见 off().

public void on ( $name, $handler, $data null, $append true )
$name 字符串

事件名称

$handler callable

事件处理程序

$data mixed

要传递给事件处理程序的数据,当事件被触发时。当事件处理程序被调用时,可以通过 yii\base\Event::$data 访问此数据。

$append boolean

是否将新的事件处理程序追加到现有处理程序列表的末尾。如果为 false,则新处理程序将插入到现有处理程序列表的开头。

                public function on($name, $handler, $data = null, $append = true)
{
    $this->ensureBehaviors();
    if (strpos($name, '*') !== false) {
        if ($append || empty($this->_eventWildcards[$name])) {
            $this->_eventWildcards[$name][] = [$handler, $data];
        } else {
            array_unshift($this->_eventWildcards[$name], [$handler, $data]);
        }
        return;
    }
    if ($append || empty($this->_events[$name])) {
        $this->_events[$name][] = [$handler, $data];
    } else {
        array_unshift($this->_events[$name], [$handler, $data]);
    }
}

            
onUnsafeAttribute() 公共方法

当不安全属性被大量分配时,将调用此方法。

默认实现将在 YII_DEBUG 打开时记录警告消息。否则它什么也不做。

public void onUnsafeAttribute ( $name, $value )
$name 字符串

不安全的属性名称

$value mixed

属性值

                public function onUnsafeAttribute($name, $value)
{
    if (YII_DEBUG) {
        Yii::debug("Failed to set unsafe attribute '$name' in '" . get_class($this) . "'.", __METHOD__);
    }
}

            
resolveFields() 受保护方法

定义于: yii\base\ArrayableTrait::resolveFields()

确定哪些字段可以由 toArray() 返回。

此方法将首先从给定的字段中提取根字段。然后,它将检查请求的根字段是否在 fields()extraFields() 中声明,以确定可以返回哪些字段。

protected array resolveFields ( array $fields, array $expand )
$fields 数组

要导出请求的字段

$expand 数组

要导出请求的附加字段

return 数组

要导出的字段列表。数组键是字段名称,数组值是相应的对象属性名称或返回字段值的 PHP 可调用函数。

                protected function resolveFields(array $fields, array $expand)
{
    $fields = $this->extractRootFields($fields);
    $expand = $this->extractRootFields($expand);
    $result = [];
    foreach ($this->fields() as $field => $definition) {
        if (is_int($field)) {
            $field = $definition;
        }
        if (empty($fields) || in_array($field, $fields, true)) {
            $result[$field] = $definition;
        }
    }
    if (empty($expand)) {
        return $result;
    }
    foreach ($this->extraFields() as $field => $definition) {
        if (is_int($field)) {
            $field = $definition;
        }
        if (in_array($field, $expand, true)) {
            $result[$field] = $definition;
        }
    }
    return $result;
}

            
rules() 公共方法

返回属性的验证规则。

验证规则由 validate() 用于检查属性值是否有效。子类可以覆盖此方法以声明不同的验证规则。

每个规则都是一个数组,具有以下结构

[
    ['attribute1', 'attribute2'],
    'validator type',
    'on' => ['scenario1', 'scenario2'],
    //...other parameters...
]

其中

  • 属性列表:必需的,指定要验证的属性数组,对于单个属性,您可以传递一个字符串;
  • 验证器类型:必需的,指定要使用的验证器。它可以是内置验证器名称、模型类的 方法名称、匿名函数或验证器类名称。
  • on:可选,指定可以应用验证规则的 场景 数组。如果未设置此选项,则规则将应用于所有场景。
  • 可以指定其他名称值对来初始化相应的验证器属性。有关可能的属性,请参阅单个验证器类 API。

验证器可以是扩展 yii\validators\Validator 的类的对象,也可以是模型类方法(称为内联验证器),该方法具有以下签名

// $params refers to validation parameters given in the rule
function validatorName($attribute, $params)

在上面的 $attribute 中,指的是当前正在验证的属性,而 $params 包含一个验证器配置选项数组,例如 string 验证器中的 max。当前正在验证的属性的值可以访问为 $this->$attribute。注意 $attribute 之前;这将获取变量 $attribute 的值并将其用作访问属性的名称。

Yii 还提供了一组 内置验证器。每个验证器都有一个别名,可以在指定验证规则时使用。

以下是一些示例

[
    // built-in "required" validator
    [['username', 'password'], 'required'],
    // built-in "string" validator customized with "min" and "max" properties
    ['username', 'string', 'min' => 3, 'max' => 12],
    // built-in "compare" validator that is used in "register" scenario only
    ['password', 'compare', 'compareAttribute' => 'password2', 'on' => 'register'],
    // an inline validator defined via the "authenticate()" method in the model class
    ['password', 'authenticate', 'on' => 'login'],
    // a validator of class "DateRangeValidator"
    ['dateRange', 'DateRangeValidator'],
];

注意,为了继承父类中定义的规则,子类需要使用 array_merge() 等函数将父规则与子规则合并。

另请参见 scenarios().

public array rules ( )
return 数组

验证规则

                public function rules()
{
    return [];
}

            
safeAttributes() 公共方法

返回在当前场景中可以被大量分配的属性名称。

public string[] safeAttributes ( )
return 字符串[]

安全属性名称

                public function safeAttributes()
{
    $scenario = $this->getScenario();
    $scenarios = $this->scenarios();
    if (!isset($scenarios[$scenario])) {
        return [];
    }
    $attributes = [];
    foreach ($scenarios[$scenario] as $attribute) {
        if (
            $attribute !== ''
            && strncmp($attribute, '!', 1) !== 0
            && !in_array('!' . $attribute, $scenarios[$scenario])
        ) {
            $attributes[] = $attribute;
        }
    }
    return $attributes;
}

            
scenarios() 公共方法

返回场景列表和相应的活动属性。

活动属性是指在当前场景下会进行验证的属性。返回的数组应具有以下格式

[
    'scenario1' => ['attribute11', 'attribute12', ...],
    'scenario2' => ['attribute21', 'attribute22', ...],
    ...
]

默认情况下,活动属性被视为安全,并且可以进行批量赋值。如果属性不应该进行批量赋值(因此被视为不安全),请在属性前加一个感叹号(例如:'!rank')。

此方法的默认实现将返回在 rules() 声明中找到的所有场景。名为 SCENARIO_DEFAULT 的特殊场景将包含在 rules() 中找到的所有属性。每个场景将与由应用于该场景的验证规则验证的属性相关联。

public array scenarios ( )
return 数组

场景及其对应活动属性的列表。

                public function scenarios()
{
    $scenarios = [self::SCENARIO_DEFAULT => []];
    foreach ($this->getValidators() as $validator) {
        foreach ($validator->on as $scenario) {
            $scenarios[$scenario] = [];
        }
        foreach ($validator->except as $scenario) {
            $scenarios[$scenario] = [];
        }
    }
    $names = array_keys($scenarios);
    foreach ($this->getValidators() as $validator) {
        if (empty($validator->on) && empty($validator->except)) {
            foreach ($names as $name) {
                foreach ($validator->attributes as $attribute) {
                    $scenarios[$name][$attribute] = true;
                }
            }
        } elseif (empty($validator->on)) {
            foreach ($names as $name) {
                if (!in_array($name, $validator->except, true)) {
                    foreach ($validator->attributes as $attribute) {
                        $scenarios[$name][$attribute] = true;
                    }
                }
            }
        } else {
            foreach ($validator->on as $name) {
                foreach ($validator->attributes as $attribute) {
                    $scenarios[$name][$attribute] = true;
                }
            }
        }
    }
    foreach ($scenarios as $scenario => $attributes) {
        if (!empty($attributes)) {
            $scenarios[$scenario] = array_keys($attributes);
        }
    }
    return $scenarios;
}

            
setAttributes() 公共方法

以大量方式设置属性值。

另请参阅

public void setAttributes ( $values, $safeOnly true )
$values 数组

要分配给模型的属性值(名称 => 值)。

$safeOnly boolean

是否只对安全属性进行赋值。安全属性是指与当前 $scenario 中的验证规则相关的属性。

                public function setAttributes($values, $safeOnly = true)
{
    if (is_array($values)) {
        $attributes = array_flip($safeOnly ? $this->safeAttributes() : $this->attributes());
        foreach ($values as $name => $value) {
            if (isset($attributes[$name])) {
                $this->$name = $value;
            } elseif ($safeOnly) {
                $this->onUnsafeAttribute($name, $value);
            }
        }
    }
}

            
setScenario() 公共方法

设置模型的场景。

请注意,此方法不会检查场景是否存在。方法 validate() 将执行此检查。

public void setScenario ( $value )
$value 字符串

此模型所在的场景。

                public function setScenario($value)
{
    $this->_scenario = $value;
}

            
toArray() 公共方法

定义于: yii\base\ArrayableTrait::toArray()

将模型转换为数组。

此方法将首先通过调用 resolveFields() 来识别哪些字段要包含在结果数组中。然后,它将模型转换为包含这些字段的数组。如果 $recursive 为 true,则任何嵌入对象也将被转换为数组。当嵌入对象为 yii\base\Arrayable 时,它们的各自嵌套字段将被提取并传递给 toArray()

如果模型实现了 yii\web\Linkable 接口,则结果数组还将包含一个 _link 元素,该元素引用接口指定的一系列链接。

public array toArray ( array $fields [], array $expand [], $recursive true )
$fields 数组

正在请求的字段。如果为空或包含“*”,则将返回由 fields() 指定的所有字段。字段可以嵌套,用点(.)分隔。例如:item.field.sub-field $recursive 必须为 true 才能提取嵌套字段。如果 $recursive 为 false,则只提取根字段。

$expand 数组

正在请求的用于导出额外的字段。只考虑在 extraFields() 中声明的字段。Expand 也可以嵌套,用点(.)分隔。例如:item.expand1.expand2 $recursive 必须为 true 才能提取嵌套的 expand。如果 $recursive 为 false,则只提取根 expand。

$recursive boolean

是否递归地返回嵌入对象的数组表示形式。

return 数组

对象的数组表示形式

                public function toArray(array $fields = [], array $expand = [], $recursive = true)
{
    $data = [];
    foreach ($this->resolveFields($fields, $expand) as $field => $definition) {
        $attribute = is_string($definition) ? $this->$definition : $definition($this, $field);
        if ($recursive) {
            $nestedFields = $this->extractFieldsFor($fields, $field);
            $nestedExpand = $this->extractFieldsFor($expand, $field);
            if ($attribute instanceof Arrayable) {
                $attribute = $attribute->toArray($nestedFields, $nestedExpand);
            } elseif ($attribute instanceof \JsonSerializable) {
                $attribute = $attribute->jsonSerialize();
            } elseif (is_array($attribute)) {
                $attribute = array_map(
                    function ($item) use ($nestedFields, $nestedExpand) {
                        if ($item instanceof Arrayable) {
                            return $item->toArray($nestedFields, $nestedExpand);
                        } elseif ($item instanceof \JsonSerializable) {
                            return $item->jsonSerialize();
                        }
                        return $item;
                    },
                    $attribute
                );
            }
        }
        $data[$field] = $attribute;
    }
    if ($this instanceof Linkable) {
        $data['_links'] = Link::serialize($this->getLinks());
    }
    return $recursive ? ArrayHelper::toArray($data) : $data;
}

            
trigger() 公共方法

定义于: yii\base\Component::trigger()

触发事件。

此方法表示事件的发生。它调用与该事件相关联的所有附加处理程序,包括类级处理程序。

public void trigger ( $name, yii\base\Event $event null )
$name 字符串

事件名称

$event yii\base\Event|null

事件实例。如果未设置,将创建一个默认的 yii\base\Event 对象。

                public function trigger($name, Event $event = null)
{
    $this->ensureBehaviors();
    $eventHandlers = [];
    foreach ($this->_eventWildcards as $wildcard => $handlers) {
        if (StringHelper::matchWildcard($wildcard, $name)) {
            $eventHandlers[] = $handlers;
        }
    }
    if (!empty($this->_events[$name])) {
        $eventHandlers[] = $this->_events[$name];
    }
    if (!empty($eventHandlers)) {
        $eventHandlers = call_user_func_array('array_merge', $eventHandlers);
        if ($event === null) {
            $event = new Event();
        }
        if ($event->sender === null) {
            $event->sender = $this;
        }
        $event->handled = false;
        $event->name = $name;
        foreach ($eventHandlers as $handler) {
            $event->data = $handler[1];
            call_user_func($handler[0], $event);
            // stop further handling if the event is handled
            if ($event->handled) {
                return;
            }
        }
    }
    // invoke class-level attached handlers
    Event::trigger($this, $name, $event);
}

            
validate() 公共方法

执行数据验证。

此方法执行适用于当前 $scenario 的验证规则。使用以下标准来确定规则当前是否适用

  • 该规则必须与与当前场景相关的属性相关联;
  • 该规则必须对当前场景有效。

此方法将在实际验证之前和之后分别调用 beforeValidate()afterValidate()。如果 beforeValidate() 返回 false,则验证将被取消,并且不会调用 afterValidate()

在验证过程中发现的错误可以通过 getErrors()getFirstErrors()getFirstError() 来检索。

public boolean validate ( $attributeNames null, $clearErrors true )
$attributeNames string[]|string|null

要验证的属性名称或属性名称列表。如果此参数为空,则意味着应验证适用于验证规则的所有属性。

$clearErrors boolean

是否在执行验证之前调用 clearErrors()

return boolean

验证是否成功,没有任何错误。

throws yii\base\InvalidArgumentException

如果当前场景未知。

                public function validate($attributeNames = null, $clearErrors = true)
{
    if ($clearErrors) {
        $this->clearErrors();
    }
    if (!$this->beforeValidate()) {
        return false;
    }
    $scenarios = $this->scenarios();
    $scenario = $this->getScenario();
    if (!isset($scenarios[$scenario])) {
        throw new InvalidArgumentException("Unknown scenario: $scenario");
    }
    if ($attributeNames === null) {
        $attributeNames = $this->activeAttributes();
    }
    $attributeNames = (array)$attributeNames;
    foreach ($this->getActiveValidators() as $validator) {
        $validator->validateAttributes($this, $attributeNames);
    }
    $this->afterValidate();
    return !$this->hasErrors();
}

            
validateMultiple() 公共静态方法

验证多个模型。

此方法将验证每个模型。正在验证的模型可以是相同类型或不同类型。

public static boolean validateMultiple ( $models, $attributeNames null )
$models 数组

要验证的模型

$attributeNames array|null

要验证的属性名称列表。如果此参数为空,则意味着应验证适用于验证规则的所有属性。

return boolean

所有模型是否有效。如果一个或多个模型存在验证错误,将返回 false。

                public static function validateMultiple($models, $attributeNames = null)
{
    $valid = true;
    /* @var $model Model */
    foreach ($models as $model) {
        $valid = $model->validate($attributeNames) && $valid;
    }
    return $valid;
}

            

事件详情

隐藏继承的属性

EVENT_AFTER_VALIDATE yii\base\Event 类型的事件

validate() 结束时触发的事件

EVENT_BEFORE_VALIDATE yii\base\ModelEvent 类型的事件

validate() 开始时引发的事件。您可以将 yii\base\ModelEvent::$isValid 设置为 false 以停止验证。