import-basics.md

Basics

This library works with ActiveRecord models.

There are 4 main types of objects, first two of them are configurable.

Standard Model

Base model to use. It contains relations to the actual ActiveRecord model class and to list of used standard attributes.

Common properties:

• className - related ActiveRecord model class name. Required. It's recommended to use className() static method of yii\db\ActiveRecord to get it. For example: Post::className().
• useAttributeLabels - either to use user-friendly attribute labels or raw names (according database column names). Defaults to true. Using this you can avoid writing author_id and write Author instead and use translations for your language.
• extendStandardAttributes - extend user defined standard attributes with missing attributes of this model. Defaults to true.
• standardAttributesConfig - list of related standard attributes with their configuration.

Import properties:

• setScenario - set separate scenario for saving models. Defaults to false. When using that, scenario is set to import, so you can configure separate validation rules for import.
• labels - list of labels used to determine this standard model in Excel data. For advanced import only. It's recommended to use singular and multiple word forms: ['Post', 'Posts'] so you can write appropriate form depending on context.

Standard Attribute

Base attribute belonging to standard model.

Properties:

• name - related attribute name. Required.
• label - user-friendly label. Optional, by default it's taken from ActiveRecord attributeLabels() list.
• valueReplacement - value mapping to avoid hard coding ids, constants or convert / format value to desired state. You can specify a list, for example: Test::getTypesList(), where getTypesList method can be declared like this:

<?php

namespace frontend\models;

use yii\db\ActiveRecord;

class Test extends ActiveRecord
{
    // Types

    /**
     * Selecting from the list of answers
     */
    const TYPE_CLOSED = 1;

    /**
     * Writing answer manually
     */
    const TYPE_OPENED = 2;

    ...

    /**
     * @return array
     */
    public static function getTypesList()
    {
       return [
           self::TYPE_CLOSED => 'Closed',
           self::TYPE_OPENED => 'Opened',
       ];
    }
}

or use a callable.

One way is to use it to get the id of related model from human readable form:

function ($value) {
    return Category::find()->select('id')->where(['name' => $value]);
},

In this case you must return ActiveQuery, not ActiveRecord or set of ActiveRecords, so do not add ->one() or ->all() to the query chain. This is needed to make sure there is exactly one matching value exists. Specifying attribute in select is also important, otherwise first attribute will be selected.

Another way is just return the new formatted value:

function ($value) {
    return $value ? Html::tag('p', $value) : '';
},

In this case we are using this as decorator to wrap text in paragraph tag to prevent writing HTML in Excel. Obviously it can be more complicated that that.

Model

Model instance containing data taken from Excel sheet row (and converted, if needed). Belongs to standard model and has some attributes.

Attribute

The value of attribute.