futuretek/yii2-options

This extension provide application configuration support stored in database.

Yii2 Options

This extension provide application configuration support stored in database., _(*1)

WARNING: Version 2.x introduces breaking changes. Upgrading from version 1.x is possible but requires additional actions., _(*2)

Steps to migrate to version 2.x: * Create options config for every used option item * Include component in Yii2 config * Rewrite commands to new syntax (or use compat class futuretek\options\compat\Option), _(*3)

Installation

The preferred way to install this extension is through composer., _(*4)

Either run, _(*5)

php composer.phar require --prefer-dist futuretek/yii2-options "*"

or add, _(*6)

"futuretek/yii2-options": "*"

to the require section of your composer.json file., _(*7)

Configuration

To start using this extension you have to load it in Yii config:, _(*8)

return [
    'components' => [
        'options' => [
            'class' => 'futuretek\options\Option',
            'configFile' => __DIR__ . '/options.php',
            'enableCaching' => true,
        ],     
    ],
];

The component itself can be configured with the following properties:, _(*9)

Notice: Option config is lazy-loaded on init (as opposite of including it in the application config). This is because the translation engine is not available at that time., _(*10)

Option config/definition array contains list of the option groups., _(*11)

Option group

Every option group consists of these attributes. Attributes marked with (*) are required., _(*12)

• title (*) - Group title
• items (*) - Contains array of option items (see below)
• visible - If the group is visible

Option items

Option group attribute items is array containing option items., _(*13)

Option item consists of these attributes. Attributes marked with (*) are required., _(*14)

• name (*) - Option name (unique)
• type (*) - Option type. See Option::TYPE_* constants.
• title (*) - Option title
• hint - Option description
• visible - If the option is visible
• default - Specify option default value. Getting defined but unset option yields this value. When not set, null will be returned.
• context - If the option is context option. If this is true, option will not be rendered using provided actions.
• data - For option type=TYPE_OPTION this attribute contains data in form of:
  1. array of arrays containing keys id and name (see example below) or
  2. anonymous function returning the same array

ADVICE: If you need to create divider between options in the same option group, simply put string as one of the items array item., _(*15)

Config example, _(*16)

return [
    [
        'title' => Yii::t('app', 'Group one'),
        'visible' => true,
        'items' => [
            ['name' => 'PHONE', 'type' => Option::TYPE_PHONE, 'title' => Yii::t('app', 'Phone number')],
            ['name' => 'EMAIL', 'type' => Option::TYPE_EMAIL, 'title' => Yii::t('app', 'Email address')],
            Yii::t('app', 'Apperance'), //Divider
            [
                'name' => 'COLOR',
                'type' => Option::TYPE_OPTION,
                'title' => Yii::t('app', 'Color scheme'),
                'data' => [
                    ['id' => 'ff0000', 'name' => 'Red'],
                    ['id' => '00ff00', 'name' => 'Green'],
                    ['id' => '0000ff', 'name' => 'Blue'],
                ],
            ],
        ],
    ],
    [
        'title' => Yii::t('app', 'Another group'),
        'visible' => YII_ENV_DEV, //Visible only in dev env
        'items' => [
            [
                'name' => 'LOGIN_TYPE',
                'type' => Option::TYPE_OPTION,
                'title' => Yii::t('app', 'Login Type'),
                'hint' => Yii::t('app', 'Please select desired login type'),
                'data' => function () {
                    return \app\classes\Tools::findAvailableLoginProviders();
                },
            ],
        ],
    ],
];

Usage

This extension creates options component for storing configuration., _(*17)

Getting options, _(*18)

$value = \Yii::$app->options->get('OPTION_NAME');

Setting options, _(*19)

\Yii::$app->options->set('OPTION_NAME', $value);

Context options, _(*20)

Context comes handy in case you need to deal with storing different configuration for multiple entities (for example user configuration)., _(*21)

In this use case context can be uses. Simply specify entity identificator as context and entity record id as context_id and you are done., _(*22)

Getting and setting options is done via another arguments of methods get() and set()., _(*23)

$userValue = \Yii::$app->options->get('OPTION_NAME', self::class, $this->getPrimaryKey());
\Yii::$app->options->set('OPTION_NAME', $userValue, self::class, $this->getPrimaryKey());

Rendering settings page

If you want to render settings page, there is futuretek\options\IndesAction provided. You can simply add it to the controller actions() method., _(*24)

There is also futuretek\options\OptionsHelper that provides method for rendering option edit field based on option type., _(*25)

See mentioned files for more details., _(*26)

Development

Translations

Translations are managed trough standard Yii2 translations. To automatically register extension translations we recommend to use our another extension futuretek/yii2-composer., _(*27)

To generate messages for translating run the following command in extension root directory., _(*28)

yii message/extract messages/config.php

Assets

Assets are managed by Compass, _(*29)

• While developing run compass watch in extension root directory
• To compile assets for final distribution run compass compile -e production --force in extension root directory.