Class yii\behaviors\AttributeTypecastBehavior

继承yii\behaviors\AttributeTypecastBehavior » yii\base\Behavior » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0.10
源代码 https://github.com/yiisoft/yii2/blob/master/framework/behaviors/AttributeTypecastBehavior.php

AttributeTypecastBehavior 提供模型属性类型自动转换的功能.

对于像 MongoDB 或 Redis 这样的无模式数据库使用 ActiveRecord 的情况, 此行为非常有用.

对于常规的 yii\db\ActiveRecordyii\base\Model, 它也可以派上用场, 允许在模型验证后保持严格的属性类型.

此行为应附加到 yii\base\Modelyii\db\BaseActiveRecord 的子类.

你应该通过 $attributeTypes 指定确切的属性类型.

例如:

use yii\behaviors\AttributeTypecastBehavior;

class Item extends \yii\db\ActiveRecord
{
    public function behaviors()
    {
        return [
            'typecast' => [
                'class' => AttributeTypecastBehavior::className(),
                'attributeTypes' => [
                    'amount' => AttributeTypecastBehavior::TYPE_INTEGER,
                    'price' => AttributeTypecastBehavior::TYPE_FLOAT,
                    'is_active' => AttributeTypecastBehavior::TYPE_BOOLEAN,
                ],
                'typecastAfterValidate' => true,
                'typecastBeforeSave' => false,
                'typecastAfterFind' => false,
            ],
        ];
    }

    // ...
}

Tip: 你可以将 $attributeTypes 留空 - 在这种情况下, 将根据所有者(owner)验证规则自动检测其值.

以下示例将自动创建与上面配置相同的 $attributeTypes 值:

use yii\behaviors\AttributeTypecastBehavior;

class Item extends \yii\db\ActiveRecord
{

    public function rules()
    {
        return [
            ['amount', 'integer'],
            ['price', 'number'],
            ['is_active', 'boolean'],
        ];
    }

    public function behaviors()
    {
        return [
            'typecast' => [
                'class' => AttributeTypecastBehavior::className(),
                // 'attributeTypes'将根据`rules()`自动组合
            ],
        ];
    }

    // ...
}

此行为允许在以下情况下自动进行属性类型转换:

  • 模型验证成功后;
  • 模型保存前(insert 或 update);
  • 模型查询后(通过查询或刷新找到).

你可以使用 $typecastAfterValidate, $typecastBeforeSave$typecastAfterFind 字段来控制对特定情况下的自动类型转换.

默认情况下, 仅在模型验证后才会执行类型转换.

Note: 你可以随时调用 typecastAttributes() 方法手动触发属性类型转换:

$model = new Item();
$model->price = '38.5';
$model->is_active = 1;
$model->typecastAttributes();

公共属性

隐藏继承的属性

属性类型描述定义在
$attributeTypes array 属性类型转换映射的格式为: attributeName => type. yii\behaviors\AttributeTypecastBehavior
$owner yii\base\Model|yii\db\BaseActiveRecord 该行为的所有者. yii\behaviors\AttributeTypecastBehavior
$skipOnNull boolean 是否跳过null值的类型转换. yii\behaviors\AttributeTypecastBehavior
$typecastAfterFind boolean 是否在从数据库中检索所有者模型数据后(在查找或刷新之后)执行类型转换. yii\behaviors\AttributeTypecastBehavior
$typecastAfterSave boolean 是否在保存所有者模型(insertupdate)之后执行类型转换. yii\behaviors\AttributeTypecastBehavior
$typecastAfterValidate boolean 是否在所有者模型验证后执行类型转换. yii\behaviors\AttributeTypecastBehavior
$typecastBeforeSave boolean 是否在保存所有者模型(insertupdate)之前后执行类型转换. yii\behaviors\AttributeTypecastBehavior

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的已命名方法. yii\base\BaseObject
__construct() 构造函数. yii\base\BaseObject
__get() 返回对象属性的值. yii\base\BaseObject
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\BaseObject
__set() 设置对象属性的值. yii\base\BaseObject
__unset() 将对象属性设置为null. yii\base\BaseObject
afterFind() 处理所有者afterFind事件, 确保属性类型转换. yii\behaviors\AttributeTypecastBehavior
afterSave() 处理所有者afterInsertafterUpdate事件, 确保属性类型转换. yii\behaviors\AttributeTypecastBehavior
afterValidate() 处理所有者afterValidate事件, 确保属性类型转换. yii\behaviors\AttributeTypecastBehavior
attach() 将行为对象附加到组件. yii\behaviors\AttributeTypecastBehavior
beforeSave() 处理所有者beforeInsertbeforeUpdate事件, 确保属性类型转换. yii\behaviors\AttributeTypecastBehavior
canGetProperty() 返回一个值, 指示属性是否可读. yii\base\BaseObject
canSetProperty() 返回一个值, 指示属性是否可写. yii\base\BaseObject
className() 返回此类的完全限定名称. yii\base\BaseObject
clearAutoDetectedAttributeTypes() 清除所有受影响的所有者类上自动检测到的 $attributeTypes 值的内部静态缓存. yii\behaviors\AttributeTypecastBehavior
detach() 从组件中分离行为对象. yii\base\Behavior
events() 声明 所有者 事件的事件处理程序. yii\behaviors\AttributeTypecastBehavior
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\BaseObject
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\BaseObject
init() 初始化对象. yii\base\BaseObject
typecastAttributes() 根据 $attributeTypes, 转换所有者属性类型. yii\behaviors\AttributeTypecastBehavior

受保护的方法

隐藏继承的方法

方法描述定义在
detectAttributeTypes() 根据所有者验证规则为 $attributeTypes 组合默认值. yii\behaviors\AttributeTypecastBehavior
typecastValue() 将给定的值转换为指定的类型. yii\behaviors\AttributeTypecastBehavior

常量

隐藏继承的常量

常量描述定义在
TYPE_BOOLEAN 'boolean' yii\behaviors\AttributeTypecastBehavior
TYPE_FLOAT 'float' yii\behaviors\AttributeTypecastBehavior
TYPE_INTEGER 'integer' yii\behaviors\AttributeTypecastBehavior
TYPE_STRING 'string' yii\behaviors\AttributeTypecastBehavior

属性详情

$attributeTypes public 属性

属性类型转换映射的格式为: attributeName => type.

类型可以通过 PHP 回调函数设置, 它可以接受原始值作为参数, 并且应该返回类型转换结果.

例如:

[
    'amount' => 'integer',
    'price' => 'float',
    'is_active' => 'boolean',
    'date' => function ($value) {
        return ($value instanceof \DateTime) ? $value->getTimestamp(): (int)$value;
    },
]

如果未设置, 将从所有者验证规则自动组合属性类型映射.

public array $attributeTypes null
$owner public 属性

该行为的所有者.

$skipOnNull public 属性

是否跳过null值的类型转换.

如果启用的属性值等于null, 则不会进行类型转换(eg. null仍为null), 否则将根据在 $attributeTypes 中配置的类型进行转换.

public boolean $skipOnNull true
$typecastAfterFind public 属性

是否在从数据库中检索所有者模型数据后(在查找或刷新之后)执行类型转换.

可以禁用此选项以获得更好的性能.

例如, 在使用 yii\db\ActiveRecord 的情况下, 查询后的类型转换在大多数情况下不会获得任何好处, 因此可以禁用它.

Note: 将此行为附加到模型后, 更改此选项值将不起作用.

public boolean $typecastAfterFind false
$typecastAfterSave public 属性 (可用自版本: 2.0.14)

是否在保存所有者模型(insertupdate)之后执行类型转换.

可以禁用此选项以获得更好的性能.

例如, 在使用 yii\db\ActiveRecord 的情况下, 保存后的类型转换将不会获得任何好处, 因此可以禁用它.

Note: 将此行为附加到模型后, 更改此选项值将不起作用.

public boolean $typecastAfterSave false
$typecastAfterValidate public 属性

是否在所有者模型验证后执行类型转换.

Note: 仅在验证成功时才执行类型转换. eg, 所有者模型没有错误.

Note: 将此行为附加到模型后, 更改此选项值将不起作用.

$typecastBeforeSave public 属性

是否在保存所有者模型(insertupdate)之前后执行类型转换.

可以禁用此选项以获得更好的性能.

例如, 在使用 yii\db\ActiveRecord 的情况下, 在保存之前进行类型转换将不会获得任何好处, 因此可以禁用它.

Note: 将此行为附加到模型后, 更改此选项值将不起作用.

方法详情

afterFind() public 方法

处理所有者afterFind事件, 确保属性类型转换.

public void afterFind ( $event )
$event yii\base\Event

事件实例.

afterSave() public 方法 (可用自版本: 2.0.14)

处理所有者afterInsertafterUpdate事件, 确保属性类型转换.

public void afterSave ( $event )
$event yii\base\Event

事件实例.

afterValidate() public 方法

处理所有者afterValidate事件, 确保属性类型转换.

public void afterValidate ( $event )
$event yii\base\Event

事件实例.

attach() public 方法

将行为对象附加到组件.

默认实现将设置 所有者 属性并附加在 事件 中声明的事件处理程序. 如果重写此方法, 请确保调用父实现.

public void attach ( $owner )
$owner yii\base\Component

要将此行为附加到的组件..

beforeSave() public 方法

处理所有者beforeInsertbeforeUpdate事件, 确保属性类型转换.

public void beforeSave ( $event )
$event yii\base\Event

事件实例.

clearAutoDetectedAttributeTypes() public static 方法

清除所有受影响的所有者类上自动检测到的 $attributeTypes 值的内部静态缓存.

public static void clearAutoDetectedAttributeTypes ( )
detectAttributeTypes() protected 方法

根据所有者验证规则为 $attributeTypes 组合默认值.

protected array detectAttributeTypes ( )
return array

属性类型映射.

events() public 方法

声明 所有者 事件的事件处理程序.

子类可以重写此方法来声明应将哪些 PHP 回调应附加到 所有者 组件的事件.

当行为附加到所有者时, 回调将附加到 所有者 的事件中; 当行为与组件分离时, 它们将与事件分离.

回调可以是以下任何一种:

  • 此行为中的方法: 'handleClick', 相当于[$this, 'handleClick']
  • 对象方法: [$object, 'handleClick']
  • 静态方法: ['Page', 'handleClick']
  • 匿名函数: function ($event) { ... }

以下是一个例子:

[
    Model::EVENT_BEFORE_VALIDATE => 'myBeforeValidate',
    Model::EVENT_AFTER_VALIDATE => 'myAfterValidate',
]
public array events ( )
return array

事件(数组键)和相应的事件处理程序方法(数组值).

typecastAttributes() public 方法

根据 $attributeTypes, 转换所有者属性类型.

public void typecastAttributes ( $attributeNames null )
$attributeNames array

应该进行类型转换的属性名称列表. 如果此参数为空, 则表示 $attributeTypes 中列出的任何属性都应该进行类型转换.

typecastValue() protected 方法

将给定的值转换为指定的类型.

protected mixed typecastValue ( $value, $type )
$value mixed

要进行类型转换的值.

$type string|callable

类型名称或可调用的类型转换.

return mixed

转换结果.