, (*1)
ActiveRecord Dynamic Attribute Extension for Yii2
This extension provides dynamic ActiveRecord attributes stored into the single field in serialized state., (*2)
For license information check the LICENSE-file., (*3)
, (*4)
Installation
The preferred way to install this extension is through composer., (*5)
Either run, (*6)
php composer.phar require --prefer-dist yii2tech/ar-dynattribute
or add, (*7)
"yii2tech/ar-dynattribute": "*"
to the require section of your composer.json., (*8)
Usage
This extension provides dynamic ActiveRecord attributes stored into the single field in serialized state.
For example: imagine we create a web site, where logged in user may customize its appearance, like changing
color schema or enable/disable sidebar and so on. In order to make this customization persistent all user's
choices should be stored into the database. In general each view setting should have its own column in the
'user' table. However, this is not very practical in case your application is under development and new
settings appear rapidly. Thus it make sense to use single text field, which will store all chosen view
parameters in the serialized string. If new option introduced there will no necessity to change 'user' table
schema.
Migration for the 'user' table creation may look like following:, (*9)
class m??????_??????_create_user extends \yii\db\Migration
{
public function up()
{
$this->createTable('User', [
'id' => $this->primaryKey(),
'username' => $this->string()->notNull(),
'email' => $this->string()->notNull(),
'passwordHash' => $this->string()->notNull(),
// ...
'viewParams' => $this->text(), // field, which stores view parameters in serialized state
]);
}
public function down()
{
$this->dropTable('User');
}
}
Heads up! In general such data storage approach is a bad practice and is not recommended to be used.
Its main drawback is inability to use dynamic attributes in condition for the search query.
It is acceptable only for the attributes, which are directly set and read for single record only, and never
used for the filter queries., (*10)
Tip: you may store dynamic attributes into 'JSON' type column instead of plain text, in case you are using modern DBMS
with built-in JSON support (e.g. MySQL >= 5.5 or PostgreSQL), however, you will have to deal with possible search
condition composition on your own - this extension does not provide explicit support for it., (*11)
This extension provides [[\yii2tech\ar\dynattribute\DynamicAttributeBehavior]] ActiveRecord behavior for
the dynamic attributes support.
For example:, (*12)
use yii\db\ActiveRecord;
use yii2tech\ar\dynattribute\DynamicAttributeBehavior;
class User extends ActiveRecord
{
public function behaviors()
{
return [
'dynamicAttribute' => [
'class' => DynamicAttributeBehavior::className(),
'storageAttribute' => 'viewParams', // field to store serialized attributes
'dynamicAttributeDefaults' => [ // default values for the dynamic attributes
'bgColor' => 'green',
'showSidebar' => true,
],
],
];
}
public static function tableName()
{
return 'User';
}
// ...
}
Once being attached [[\yii2tech\ar\dynattribute\DynamicAttributeBehavior]] allows its owner to operate
dynamic attributes just as regular one. On model save they will be serialized and stored into the holding
field. After record is fetched from database the first attempt to read the dynamic attributes will unserialize
them and prepare for the usage.
For example:, (*13)
$model = new User();
// ...
$model->bgColor = 'red';
$model->showSidebar = false;
$model->save(); // 'bgColor' and 'showSidebar' are serialized and stored at 'viewParams'
echo $model->viewParams; // outputs: '{"bgColor": "red", "showSidebar": false}'
$refreshedModel = User::findOne($model->getPrimaryKey());
echo $refreshedModel->bgColor; // outputs 'red'
echo $refreshedModel->showSidebar; // outputs 'false'
You may use dynamic attributes as the regular ActiveRecord attributes. For example: you may
specify the validation rules for them and obtain their values via web form., (*14)
Note: keep in mind that dynamic attributes do not correspond to ActiveRecord entity fields, thus
some particular ActiveRecord methods like updateAttributes() will not work for them., (*15)
Default values setup
As you may note from above example, you can provide a default values for the dynamic attributes
via [[\yii2tech\ar\dynattribute\DynamicAttributeBehavior::$dynamicAttributeDefaults]].
Thus once you need extra dynamic attribute for your model you can just update the dynamicAttributeDefaults
list with corresponding value, without necessity to perform any updates on your database., (*16)
class User extends ActiveRecord
{
public function behaviors()
{
return [
'dynamicAttribute' => [
'class' => DynamicAttributeBehavior::className(),
'storageAttribute' => 'viewParams',
'dynamicAttributeDefaults' => [
'bgColor' => 'green',
'showSidebar' => true,
'fontColor' => 'black', // newly added attribute
],
],
];
}
// ...
}
$newModel = new User();
echo $newModel->bgColor; // outputs 'green'
echo $newModel->showSidebar; // outputs 'true'
$oldModel = User::find()->orderBy(['id' => SORT_ASC])->limit(1)->one();
echo $oldModel->viewParams; // outputs: '{"bgColor": "red", "showSidebar": false}'
echo $oldModel->fontColor; // outputs: 'black'
Note: you may exclude dynamic attribute, which value equals the default one, from saving disabling
[[\yii2tech\ar\dynattribute\DynamicAttributeBehavior::$saveDynamicAttributeDefaults]] option., (*17)
Restrict dynamic attribute list
Setup of the dynamic attribute default values not only useful, but in general is necessary.
This list puts a restriction on the possible dynamic attribute names. Only attributes, which
have default value specified can be set or read from the model. This prevents the possible mistakes
caused by typos in the code.
For example:, (*18)
$newModel = new User();
$newModel->bgColor = 'blue'; // works fine
$newModel->unExistingAttribute = 10; // throws an exception!
However sometimes there is necessity of storage list of attributes, which can not be predicted.
For example, saving response fields from some external service.
In this case you can disable check performed on attribute setter using
[[\yii2tech\ar\dynattribute\DynamicAttributeBehavior::$allowRandomDynamicAttribute]].
If it is set to true you will be able to setup any dynamic attribute no matter declared or not
at dynamicAttributeDefaults., (*19)
Note: you can also use [[\yii2tech\ar\dynattribute\DynamicAttributeBehavior::setDynamicAttributes()]] method
to bypass naming restriction. This method will set all provided attributes without any checks., (*20)
You can as well control the dynamic attributes list to be actually saved using [[\yii2tech\ar\dynattribute\DynamicAttributeBehavior::$dynamicAttributeSaveFilter]].
If set to true it will exclude any attribute, which is not listed at dynamicAttributeDefaults option. You may as
well specify it as a PHP callback, which will perform some custom filtering. This option allows you to remove obsolete
dynamic attributes, which existed in the past, but no longer actual., (*21)
Serializer setup
By default [[\yii2tech\ar\dynattribute\DynamicAttributeBehavior]] saves the dynamic attribute in JSON
format. However, you may setup another serializer for them via [[\yii2tech\ar\dynattribute\DynamicAttributeBehavior::$serializer]].
The following serializers are available withing this extension:, (*22)
- [[\yii2tech\ar\dynattribute\JsonSerializer]] - stores data in JSON format
- [[\yii2tech\ar\dynattribute\PhpSerializer]] - stores data using PHP
serialize()/unserialize() functions
- [[\yii2tech\ar\dynattribute\CallbackSerializer]] - stores data via custom serialize PHP callback.
- [[\yii2tech\ar\dynattribute\JsonExpressionSerializer]] - handles [[yii\db\JsonExpression]] instances, supporting usage of 'JSON' DB column types.
Please refer to the particular serializer class for more details., (*23)
Wallogit.com
