Merge pull request #6 from yii2mod/add_settings_action

close #5

.travis.yml

@@ -1,9 +1,8 @@
 language: php
 
 php:
-  - 5.5
   - 5.6
-  - 7.0
+  - 7.1
 
 # faster builds on new travis setup not using sudo
 sudo: false
@@ -16,7 +15,7 @@ cache:
 
 install:
   - travis_retry composer self-update && composer --version
-  - travis_retry composer global require "fxp/composer-asset-plugin:~1.1.1"
+  - travis_retry composer global require "fxp/composer-asset-plugin:^1.2.0"
   - export PATH="$HOME/.composer/vendor/bin:$PATH"
   - travis_retry composer install --prefer-dist --no-interaction
 

README.md

@@ -104,6 +104,124 @@ $settings->removeAll();
 $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:
+
+1) Create your own model, for example:
+
+```php
+<?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'),
+        ];
+    }
+}
+```
+
+2) Create view file, named `settings.php` with the following content:
+
+```php
+<?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(); ?>
+
+```
+
+3) Add settings action to your controller class as follows:
+
+```php
+<?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
 ----------------------
 

actions/SettingsAction.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace yii2mod\settings\actions;
+
+use Yii;
+use yii\base\Action;
+use yii\base\InvalidConfigException;
+use yii\helpers\ArrayHelper;
+use yii2mod\settings\events\FormEvent;
+
+/**
+ * Class SettingsAction
+ *
+ * @package yii2mod\settings\actions
+ */
+class SettingsAction extends Action
+{
+    /**
+     * Event is triggered before the settings will be saved.
+     * Triggered with \yii2mod\settings\events\FormEvent.
+     */
+    const EVENT_BEFORE_SAVE = 'beforeSave';
+
+    /**
+     * Event is triggered after the settings have been saved successfully.
+     * Triggered with \yii2mod\settings\events\FormEvent.
+     */
+    const EVENT_AFTER_SAVE = 'afterSave';
+
+    /**
+     * @var string class name of the model which will be used to validate the attributes
+     */
+    public $modelClass;
+
+    /**
+     * @var string message to be set on successful save a model
+     */
+    public $successMessage = 'Settings have been saved successfully.';
+
+    /**
+     * @var string the name of the settings view
+     */
+    public $view = 'settings';
+
+    /**
+     * @var array additional view params
+     */
+    public $viewParams = [];
+
+    /**
+     * @inheritdoc
+     */
+    public function init()
+    {
+        parent::init();
+
+        if ($this->modelClass === null) {
+            throw new InvalidConfigException('The "modelClass" property must be set.');
+        }
+    }
+
+    /**
+     * Renders the settings form.
+     *
+     * @return string
+     */
+    public function run()
+    {
+        $model = Yii::createObject($this->modelClass);
+        $event = Yii::createObject(['class' => FormEvent::class, 'form' => $model]);
+
+        if ($model->load(Yii::$app->request->post()) && $model->validate()) {
+            $this->trigger(self::EVENT_BEFORE_SAVE, $event);
+
+            foreach ($model->toArray() as $key => $value) {
+                Yii::$app->settings->set($model->formName(), $key, $value);
+            }
+
+            $this->trigger(self::EVENT_AFTER_SAVE, $event);
+
+            if ($this->successMessage !== null) {
+                Yii::$app->session->setFlash('success', $this->successMessage);
+            }
+        }
+
+        foreach ($model->attributes() as $attribute) {
+            $model->{$attribute} = Yii::$app->settings->get($model->formName(), $attribute);
+        }
+
+        return $this->controller->render($this->view, ArrayHelper::merge($this->viewParams, [
+            'model' => $model,
+        ]));
+    }
+}

events/FormEvent.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace yii2mod\settings\events;
+
+use yii\base\Event;
+use yii\base\Model;
+
+/**
+ * Class FormEvent
+ *
+ * @package yii2mod\settings\events
+ */
+class FormEvent extends Event
+{
+    /**
+     * @var Model
+     */
+    private $_form;
+
+    /**
+     * @return Model
+     */
+    public function getForm()
+    {
+        return $this->_form;
+    }
+
+    /**
+     * @param Model $form
+     */
+    public function setForm(Model $form)
+    {
+        $this->_form = $form;
+    }
+}