Persistent, application-wide settings for Yii2.
Support us
Does your business depend on our contributions? Reach out and support us on Patreon.
All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.
Installation
The preferred way to install this extension is through composer.
Either run
php composer.phar require --prefer-dist yii2mod/yii2-settings "*"
or add
"yii2mod/yii2-settings": "*"
to the require section of your composer.json.
Configuration
Database Migrations
Before usage this extension, we'll also need to prepare the database.
php yii migrate --migrationPath=@vendor/yii2mod/yii2-settings/migrations
Module Setup
To access the module, you need to configure the modules array in your application configuration:
'modules' => [
'settings' => [
'class' => 'yii2mod\settings\Module',
],
],
You can then access settings management section through the following URL:
http://localhost/path/to/index.php?r=settings
or if you have enabled pretty URLs, you may use the following URL:
http://localhost/path/to/index.php/settings
Component Setup
To use the Setting Component, you need to configure the components array in your application configuration:
'components' => [
'settings' => [
'class' => 'yii2mod\settings\components\Settings',
],
],
Usage:
$settings = Yii::$app->settings;
$value = $settings->get('section', 'key');
$settings->set('section', 'key', 125.5);
$settings->set('section', 'key', 'false', SettingType::BOOLEAN_TYPE);
// Checking existence of setting
$settings->has('section', 'key');
// Activates a setting
$settings->activate('section', 'key');
// Deactivates a setting
$settings->deactivate('section', 'key');
// Removes a setting
$settings->remove('section', 'key');
// Removes all settings
$settings->removeAll();
// Get's all values in the specific section.
$settings->getAllBySection('section');
$settings->invalidateCache(); // automatically called on set(), remove();
Manage custom settings
You can use your own form model to manage custom settings for your web application via SettingsAction.
To use the SettingsAction class you need to follow the following steps:
- Create your own model, for example:
<?php
namespace app\models\forms;
use Yii;
use yii\base\Model;
class ConfigurationForm extends Model
{
/**
* @var string application name
*/
public $appName;
/**
* @var string admin email
*/
public $adminEmail;
/**
* @inheritdoc
*/
public function rules(): array
{
return [
[['appName', 'adminEmail'], 'required'],
];
}
/**
* @inheritdoc
*/
public function attributeLabels(): array
{
return [
'appName' => Yii::t('app', 'Application Name'),
'adminEmail' => Yii::t('app', 'Admin Email'),
];
}
}
- Create view file, named
settings.phpwith the following content:
<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;
/* @var $model \app\models\forms\ConfigurationForm */
/* @var $this \yii\web\View */
$this->title = Yii::t('app', 'Manage Application Settings');
?>
<?php $form = ActiveForm::begin(); ?>
<?php echo $form->field($model, 'appName'); ?>
<?php echo $form->field($model, 'adminEmail'); ?>
<?php echo Html::submitButton(Yii::t('app', 'Save'), ['class' => 'btn btn-success']) ?>
<?php ActiveForm::end(); ?>
- Add settings action to your controller class as follows:
<?php
namespace app\controllers;
use yii\web\Controller;
/**
* Class SiteController
*
* @package app\controllers
*/
class SiteController extends Controller
{
/**
* @inheritdoc
*/
public function actions()
{
return [
'manage-settings' => [
'class' => \yii2mod\settings\actions\SettingsAction::class,
// also you can use events as follows:
'on beforeSave' => function ($event) {
// your custom code
},
'on afterSave' => function ($event) {
// your custom code
},
'modelClass' => \app\models\forms\ConfigurationForm::class,
],
];
}
}
Now you can access to the settings page by the following URL: http://localhost/path/to/index.php?r=site/manage-settings/
Internationalization
All text and messages introduced in this extension are translatable under category 'yii2mod.settings'.
You may use translations provided within this extension, using following application configuration:
return [
'components' => [
'i18n' => [
'translations' => [
'yii2mod.settings' => [
'class' => 'yii\i18n\PhpMessageSource',
'basePath' => '@yii2mod/settings/messages',
],
// ...
],
],
// ...
],
// ...
];