inspirenmy/yii2-config

Yii2 extension which allows to get application parameters, text or email templates from database tables or from default config, to import and to manage them from admin panel dynamically.

v0.3.7 2017-09-22 06:39 UTC

Requires

• php: >5.5.0
• inspirenmy/yii2-helpers: *
• inspirenmy/yii2-models: *
• inspirenmy/yii2-traits: *
• yiisoft/yii2: ~2.0.0

MIT

• inspirenmy

• mailer
• template
• email
• config
• extension
• template engine
• component
• yii
• yii2

README

#Yii2 extension - Config

##Description

Yii2 extension which allows to get application parameters, text or email templates from database tables or from default config, to import and to manage them from admin panel dynamically.

This extension contains following components:

1. Config component
2. Template engine component
3. Email template engine and composer engine component

##Contents

• Description
• Install
• Config component
  • Configure
    • Simple setup
    • Flexible setup
    • Configure of event handler
  • Usage
    • Frontend
      • Get param of config application
      • Get array of config's parameters by key's mask
      • Get application's param
      • Using Configurator for configuring other components
        • Modify config file directly
        • Bootstraps of components
    • Backend
• Template engine component
• Email template engine and composer engine component

##Install

1. Get from composer

composer require inspirenmy/yii2-config

or add dependency at composer.json in "require" section

"inspirenmy/yii2-config": "*"

1. Create DB tables for config storage and templates storage manually or using migration mechanism (copy files demo/tbl_config.php, demo/tbl_template.php and demo/tbl_email_template.php to migrations folder).

##Config component

Allows to get params from database table or if it doesn't exists then from following source:

• directly from method call param
• from application params file
• from custom separate config file

Allows to set params while initializing any components:

• directly at configuration section of target component in app config file
• at configuration section of config component using bootstrap section in app config file
• at call \Yii::createObject in configuration section while initializing any components

###Configure

####Simple setup

return [
    //...
    'components' => [
        //...
        'config' => 'inspirenmy\config\Configurator',
    ],
];

####Flexible setup There are several params of Configurator class which can be modified:

• class (class)
• name of config storage DB table (tableName)
• filename of custom default config params (defaultConfigFile)

return [
    //...
    'components' => [
        //...
        'config' => [
            'class' => 'inspirenmy\config\Configurator',
            'tableName' => 'tbl_config',
            'defaultConfigFile' => '@common/data/default.php',
        ],
    ],
];

####Configure of event handler There are several params of component class which can be modified:

• class (class)
• filename of missing storage (fileStorage)
• dirname of missing storage (folderStorage)

Important

Folder specified as folderStorage should be exist. Here fileStorage file will be created if some config params will be exist. Recommended to create folder previously with .gitkeep file inside.

return [
    //...
    'components' => [
        //...
        'config' => [
            //...
            'handler' => [
                'class' => 'testHandler',
                'config'=> [
                    'fileStorage' => 'missing_configs',
                    'folderStorage' => '@common/data/',
                ],
            ],
        ],
    ],
];

###Usage

Possibility of modifying system configs and templates by web application admin is target of this extension so all usages will realize modify function.

Try to use complex name in dotted style as param key at format: moduleName.paramName or moduleName.submoduleName.paramName. Do not use appconfig as moduleName. This is reserved.

####Frontend

#####Get param of config application

Get application config param from DB or \Yii::$app->params array.

Getter sequentially passes following steps. If it finds out value the pass breaks. Flow here:

• internal class variable (use if this param had been requested)
• cache (use default \Yii::$app->cache)
• DB table (use tableName table)
• custom param defaultValue (if second param defaultValue was set)
• custom default config params array (defaultConfigFile)
• array \Yii::$app->params In the end, if no value will be found then Exception will be throwed.

\Yii::$app->config->get('paramName');

or

\Yii::$app->config->get('paramName', 'defaultValue');

If param's value doesn't exists at DB table (or cached view) it will be added to missing config file by handler (fileStorage). After that web application administrator can import missing values (and all defaults also) into DB table and modify them.

If some config param need more secure level of setup you can use local param file to avoid commit them at public repo.

#####Get array of config's parameters by key's mask

Get array of config's parameters by key's mask from DB.

Getter sequentially passes following steps. If it finds out value the pass breaks. Flow here:

• internal class variable (use if this param had been requested)
• cache (use default \Yii::$app->cache)
• DB table (use tableName table) In the end, if no value by key mask will be found then empty array will be appeared as a result.

\Yii::$app->config->getLike('beginParamName');

For example,

\Yii::$app->config->getLike('someModule');

will return all params linked with someModule:

• someModule.param1
• someModule.param2
• someModule.submodule.param1
• ...

#####Get application's param

Get application param from DB or \Yii::$app.

\Yii::$app->config->app('paramName');

For example,

\Yii::$app->config->app('name');

will return your application name storing at DB or if it absent directly from application config (\Yii::$app->name).

#####Using Configurator for configuring other components

######Modify config file directly

Configurator can be used for pre-configuring other components at config file directly. These components should contain and use ConfigurableTrait (example see at demo).

For example configuring sms component with sms.senderNumber param:

// ...
'sms' => [
    'class' => 'inspirenmy\sms\Sender',
    'senderNumber' => [
        'component' => 'config',
        'sms.senderNumber' => 'AppName',
    ],
],

######Bootstraps of components

Either Configurator can pre-configure other component implementing bootstrap interface.

Add config component to app bootstrap section:

return [
    // ...
    'bootstrap' => [..., 'config', ...],
    // ...
],

Then fill bootstrap component section:

return [
    //...
    'components' => [
        //...
        'config' => [
            //...
            'bootstrap' => [
                'cloudStorage' => [
                    'key' => 'cloud_amazons3_key',
                    'secret' => 'cloud_amazons3_secret',
                    'bucket' => 'cloud_amazons3_bucket',
                    'cloudStorageBaseUrl' => 'cloud_amazons3_baseurl',
                ],
                'upload' => [
                    'externalStorageBaseUrl' => 'cloud_amazons3_baseurl',
                ],
            ],
        ],
    ],
];

and add cloud_amazons3_bucket, cloud_amazons3_baseurl, cloud_amazons3_baseurl to params array (or set default params file) either add cloud_amazons3_key, cloud_amazons3_secret to local params to protect them.

####Backend

In backend part should be used ConfiguratorAdmin class or inheritances. It use ConfiguratorAdminTrait which allow import missing config from fileStorage file or default config from defaultConfigFile file (if exists).

Administrator of the web application can:

• get list of configs, filter and sort them using your app admin grid schema (using standard IndexAction or etc.)
• modify config exists (using standard UpdateAction or etc.)
• import absent config (using admin/ImportMissingAction)
• import default config if defaultConfigFile file exists (using admin/ImportDefaultAction)

##Template engine component

Allows to get template from database table or if it doesn't exists then from template source file. Before return it replaces all matches of template variables.

Configuring process is very similar with Config component except name of class - use inspirenmy\template\TemplateEngine.

Usage process is very similar to get param of config application. Getter sequentially passes following steps. If it finds out value the pass breaks. Flow here:

• internal class variable (use if this param had been requested)
• DB table (use tableName table)
• template source file at templateFolder folder having templateExt extension In the end, if no value will be found then Exception will be throwed.

\Yii::$app->template->get('templateName');

or

\Yii::$app->template->get('templateName', ['param1' => 'value1', 'param2' => 'value2']);

If template doesn't exists at DB table it will be added to missing template file by handler (fileStorage). After that web application administrator can import missing templates into DB table and modify them.

Other processes are similar to Config component's processes.

##Email template engine and composer engine component

Allows to get email params like subject, template's name from DB and then use template from prepared the file store (where it can be modified from backend by admin) or if it doesn't exists then from mail template source file.

Configuring process is very similar with Config component except name of class - use inspirenmy\template\Mailer.

Usage process is very similar to get param of config application. Getter sequentially passes following steps. If it finds out value the pass breaks. Flow here:

• internal class variable (use if this param had been requested)
• DB table (use tableName table)
• template source file at mailerComponentViewPath folder In the end, if no template will be found then Exception will be throwed.

\Yii::$app->setTemplate('email_key')->setTo('email')->send();

or more detail

\Yii::$app->email
    ->setTemplate('test-html.php')
    ->setTo('[e-mail]')
    ->setFrom('admin@localhost')
    ->setSubject('Your account on ' . $appName)
    ->setParams(['user' => $this, 'appName' => $appName])
    ->send();

If template doesn't exists at DB table it will be added to missing template file by handler (fileStorage). After that web application administrator can import missing templates into DB table and modify them.

If param redirectEmail will be configured then all emails will be redirected to this email (field to will be ignored). If param isTransferEnabled is set to false then mailer's option useFileTransport will be set to true instead of real transfer mail.

Other processes are similar to Config component's processes.