ActiveRecord Variation Extension for Yii 2

This extension provides support for ActiveRecord variation via related models. In particular it allows implementing i18n feature for ActiveRecord.

For license information check the LICENSE-file.

Installation

The preferred way to install this extension is through composer.

Either run

or add

to the require section of your composer.json.

Usage

This extension provides support for ActiveRecord variation via related models. Variation means some particular entity have an attributes (fields), which values should vary depending on actual selected option. In database structure variation is implemented as many-to-many relation with extra columns at junction entity.

The most common example of such case is i18n feature: imagine we have an item, which title and description should be provided on several different languages. In relational database there will be 2 different tables for this case: one for the item and second - for the item translation, which have item id and language id along with actual title and description. A DDL for such solution will be following:

Usually in most cases there is no need for 'Item' to know about all its translations - it is enough to fetch only one, which is used as web application interface language.

This extension provides [[\yii2tech\ar\variation\VariationBehavior]] ActiveRecord behavior for such solution support in Yii2. You'll have to create an ActiveRecord class for 'Language', 'Item' and 'ItemTranslation' and attach [[\yii2tech\ar\variation\VariationBehavior]] in the following way:

Pay attention to the fact behavior is working through the 'has many' relation declared in the main ActiveRecord to the variation ActiveRecord. In the above example it will be relation 'translations'. You also have to declare default variation relation as 'has one', this can be easily done via [[\yii2tech\ar\variation\VariationBehavior::hasDefaultVariationRelation()]] method. Such relation inherits all information from the source one and applies extra condition on variation option reference, which is determined by [[\yii2tech\ar\variation\VariationBehavior::defaultVariationOptionReference]]. This reference should provide default value, which matches value of [[\yii2tech\ar\variation\VariationBehavior::variationOptionReferenceAttribute]] of the variation entity.

Accessing variation attributes

Having defaultVariationRelation is important for the usage of the variation attributes. Being applied [[\yii2tech\ar\variation\VariationBehavior]] allows access to the variation fields as they were the main one:

If it could be the main entity don't have a variation for particular option, you can use [[\yii2tech\ar\variation\VariationBehavior::$variationAttributeDefaultValueMap]] to provide the default value for the variation fields as it was done for 'title' in the above example:

Querying variations

As it has been already said [[\yii2tech\ar\variation\VariationBehavior]] works through relations. Thus, in order to make variation attributes feature work, it will perform an extra query to retrieve the default variation model, which may produce performance impact in case you are working with several models. In order to reduce number of queries you may use with() on the default variation relation:

You may as well use main variations relation in with(). In this case default variation will be fetched from it without extra query:

If you are using relational database you can also use [[\yii\db\ActiveQuery::joinWith()]]:

You may apply 'with' for the variation relation as default scope for the main ActiveRecord query:

Access particular variation

You can always access default variation model via getDefaultVariationModel() method:

However, in some cases there is a need of accessing particular variation, but not default one. This can be done via getVariationModel() method:

Note: method getVariationModel() will load [[\yii2tech\ar\variation\VariationBehavior::variationsRelation]] relation fully, which may reduce performance. You should always prefer usage of [[getDefaultVariationModel()]] method if possible. You may also use eager loading for variationsRelation with extra condition filtering the results in order to save performance.

Creating variation setup web interface

Usage of [[\yii2tech\ar\variation\VariationBehavior]] simplifies management of variations and creating a web interface for their setup.

The web controller for variation management may look like following:

Note that variation models should be populated with data from request manually, but they will be validated and saved automatically - you don't need to do this manually. Automatic processing of variation models will be performed only, if they have been fetched before owner validation or saving triggered. Thus it will not affect pure owner validation or saving.

The form view file can be following:

Saving default variation

It is not necessary to process all possible variations at once - you can operate only single variation model, validating and saving it. For example: you can provide a web interface where user can setup only the translation for the current language. Doing so it is better to setup [[\yii2tech\ar\variation\VariationBehavior::$variationAttributeDefaultValueMap]] value, allowing magic access to the variation attributes. Being fetched default variation model will be validated and saved along with the main model:

In case attribute in mentioned at [[\yii2tech\ar\variation\VariationBehavior::$variationAttributeDefaultValueMap]], it will be available for setting as well, even if default variation model does not exists: in such case it will be created automatically. For example:

Marking variation attributes at the main model as 'safe' you can create a web interface, which sets up them in a simple way. Model code should look like following:

Inside the view you can use variation attributes at the main model directly:

Then the controller code will be simple:

Additional variation conditions

There are case, when variation options or variation entities have extra filtering conditions or attributes. For example: assume we have a database of the developers with their payment rates, which varies per particular work type. Work types are grouped by categories: 'front-end', 'back-end', 'database' etc. And payment rates should be set for regular working time and for over-timing separately. The DDL for such use case can be following:

In this case you may want to setup 'front-end' and 'back-end' separately (using different web interface or something). You can apply an extra filtering condition for the 'option' Active Record query using [[\yii2tech\ar\variation\VariationBehavior::optionQueryFilter]]:

In this case you'll have to access getVariationModels() from the behavior instance rather then the owner directly:

You may as well separate variations using 'overtime' conditions: setup regular time and overtime payment rates in different process. For such purpose you'll have to declare 2 separated relations for 'regular time' and 'overtime' payment rates:

In this case variation will be loaded only for particular rate type and saved with corresponding value of the isOvertime flag attribute. However, automatic detection of the extra variation model attributes will work only for 'hash' query conditions. If you have a complex variation option filtering logic, you'll need to setup [[\yii2tech\ar\variation\VariationBehavior::variationModelDefaultAttributes]] manually.

In the example above you may not want to save empty variation data in database: if particular developer have no particular 'front-end' skill like 'AngularJS' he have no payment rate for it and thus there is no reason to save an empty 'PaymentRate' record for it. You may use [[\yii2tech\ar\variation\VariationBehavior::variationSaveFilter]] to determine which variation record should be saved or not. For example: