diff options
author | Thomas Steur <thomas.steur@gmail.com> | 2013-10-24 02:29:43 +0400 |
---|---|---|
committer | Thomas Steur <thomas.steur@gmail.com> | 2013-10-24 02:29:43 +0400 |
commit | e8456f5942e34b6409570fb9a4bf61d75e219a33 (patch) | |
tree | f2decd03a231c45b31260eaea34f42354739e8ea /core/Settings/Setting.php | |
parent | 0abe2b8e7de4ada6d1d8c9e693e6c17dbe986bbc (diff) |
refs #4126 added some documentation and removed some unused methods
Diffstat (limited to 'core/Settings/Setting.php')
-rw-r--r-- | core/Settings/Setting.php | 119 |
1 files changed, 103 insertions, 16 deletions
diff --git a/core/Settings/Setting.php b/core/Settings/Setting.php index 4cc443b532..43bbd49149 100644 --- a/core/Settings/Setting.php +++ b/core/Settings/Setting.php @@ -15,23 +15,113 @@ use Piwik\Piwik; use Piwik\Plugin\Settings; /** - * Settings manager + * Base setting class. Extend this class to define your own type of setting. * * @package Piwik * @subpackage Settings */ abstract class Setting { - public $type = Settings::TYPE_STRING; - public $field = Settings::FIELD_TEXT; + /** + * Defines the PHP type of the setting. Before the value is saved it will be cased depending on this setting. + * + * @var string + */ + public $type = Settings::TYPE_STRING; + + /** + * Defines which field type should be displayed on the setting page. + * + * @var string + */ + public $field = Settings::FIELD_TEXT; + + /** + * An array of field attributes that will be added as HTML attributes to the HTML form field. + * Example: `array('size' => 3)`. Please note the attributes will be escaped for security. + * @var array + */ public $fieldAttributes = array(); - public $fieldOptions = null; + + /** + * Defines available options in case you want to give the user the possibility to select a value (in a select + * field). For instance `array('nb_visits' => 'Visits', 'nb_actions' => 'Actions')`. + * In case field options are set and you do not specify a validator, a validator will be automatically added + * to check the set value is one of the defined array keys. An error will be triggered in case a user tries to + * save a value that is not allowed. + * + * @var null|array + */ + public $fieldOptions = null; + + /** + * Defines an introduction that will be displayed as a text block above the setting. + * @var null|string + */ public $introduction = null; + + /** + * Defines a description that will be displayed underneath the setting title. It should be just a short description + * what the setting is about. + * @var null|string + */ public $description = null; + + /** + * The inline help will be displayed in a separate help box next to the setting and can contain some further + * explanations about the setting. For instance if only some specific characters are allowed to can explain them + * here. + * @var null|string + */ public $inlineHelp = null; - public $filter = null; + + /** + * If a closure is set, the closure will be executed before a new value is saved. In case a user tries to save an + * invalid value just throw an exception containing a useful message. Example: + * ``` + * function ($value, Setting $setting) { + * if ($value > 60) { + * throw new \Exception('Value has to be at <= 60 as an hour has only 60 minutes'); + * } + * } + * ``` + * + * @var null|\Closure + */ public $validate = null; + + /** + * You can define a filter closure that is executed after a value is validated. In case you define a value, the + * property `$type` has no effect. That means the value won't be casted to the specified type. It is on your own to + * cast or format the value on your needs. Make sure to return a value at the end of the function as this value + * will be saved. Example: + * ``` + * function ($value, Setting $setting) { + * if ($value > 30) { + * $value = 30; + * } + * + * return (int) $value; + * } + * ``` + * + * @var null|\Closure + */ + public $filter = null; + + /** + * Defines the default value for this setting that will be used in case the user has not specified a value so far. + * The default value won't be casted so make sure to define an appropriate value. + * + * @var mixed + */ public $defaultValue = null; + + /** + * Defines the title of the setting which will be visible to the user. For instance `Refresh Interval` + * + * @var string + */ public $title = ''; protected $key; @@ -43,10 +133,17 @@ abstract class Setting return $this->displayedForCurrentUser; } + /** + * Creates a new setting. + * + * @param string $name The name of the setting, only alnum characters are allowed. For instance `refreshInterval` + * @param string $title The title of the setting which will be visible to the user. For instance `Refresh Interval` + * + * @throws \Exception In case the name contains invalid characters. + */ public function __construct($name, $title) { if (!ctype_alnum($name)) { - // TODO escape name? $msg = sprintf('The setting name %s is not valid. Only alpha and numerical characters are allowed', $name); throw new \Exception($msg); } @@ -61,11 +158,6 @@ abstract class Setting return $this->name; } - public function getTitle() - { - return $this->title; - } - /** * Returns the key under which property name the setting will be stored. * @@ -76,11 +168,6 @@ abstract class Setting return $this->key; } - public function hasKey($key) - { - return $key == $this->getKey(); - } - public function getDefaultType($field) { $defaultTypes = array( |