diff options
author | diosmosis <benakamoorthi@fastmail.fm> | 2013-10-20 13:07:34 +0400 |
---|---|---|
committer | diosmosis <benakamoorthi@fastmail.fm> | 2013-10-21 07:25:59 +0400 |
commit | f7e702843d51c281f98044d064b7379e2f653992 (patch) | |
tree | e8b75e77766040aab1db807a9c41303d56b9149d /core/Option.php | |
parent | e74ecaf307804e0f9d37c7842f9fbbd9f36ba8bb (diff) |
Refs #4200, documented several more classes.
Diffstat (limited to 'core/Option.php')
-rw-r--r-- | core/Option.php | 69 |
1 files changed, 44 insertions, 25 deletions
diff --git a/core/Option.php b/core/Option.php index b86f572c02..8c90022f99 100644 --- a/core/Option.php +++ b/core/Option.php @@ -11,20 +11,38 @@ namespace Piwik; /** - * Option provides a very simple mechanism to save/retrieve key-values pair - * from the database (persistent key-value datastore). - * - * This is useful to save Piwik-wide preferences, configuration values. + * Convenient key-value storage for user specified options and temporary + * data that needs to be persisted beyond one request. + * + * ### Examples + * + * **Setting and getting options** + * + * $optionValue = Option::get('MyPlugin.MyOptionName'); + * if ($optionValue === false) { + * // if not set, set it + * Option::set('MyPlugin.MyOptionName', 'my option value'); + * } + * + * **Storing user specific options** + * + * $userName = // ... + * Option::set('MyPlugin.MyOptionName.' . $userName, 'my option value'); + * + * **Clearing user specific options** + * + * Option::deleteLike('MyPlugin.MyOptionName.%'); * * @package Piwik + * @api */ class Option { /** - * Returns the option value for the requested option $name, fetching from database, if not in cache. - * - * @param string $name Key - * @return string|bool Value or false, if not found + * Returns the option value for the requested option `$name`. + * + * @param string $name The option name. + * @return string|bool The value or false, if not found. */ public static function get($name) { @@ -32,11 +50,12 @@ class Option } /** - * Sets the option value in the database and cache + * Sets an option value by name. * - * @param string $name - * @param string $value - * @param int $autoLoad if set to 1, this option value will be automatically loaded; should be set to 1 for options that will always be used in the Piwik request. + * @param string $name The option name. + * @param string $value The value to set the option to. + * @param int $autoLoad If set to 1, this option value will be automatically loaded when Piwik is initialzed; + * should be set to 1 for options that will be used in every Piwik request. */ public static function set($name, $value, $autoload = 0) { @@ -44,10 +63,10 @@ class Option } /** - * Delete key-value pair from database and reload cache. + * Deletes an option. * - * @param string $name Key to match exactly - * @param string $value Optional value + * @param string $name Option name to match exactly. + * @param string $value If supplied the option will be deleted only if its value matches this value. */ public static function delete($name, $value = null) { @@ -55,22 +74,23 @@ class Option } /** - * Delete key-value pair(s) from database and reload cache. - * The supplied pattern should use '%' as wildcards, and literal '_' should be escaped. + * Deletes all options that match the supplied pattern. * - * @param string $name Pattern of key to match. - * @param string $value Optional value + * @param string $namePattern Pattern of key to match. `'%'` characters should be used as wildcards, and literal + * `'_'` characters should be escaped. + * @param string $value If supplied options will be deleted only if their value matches this value. */ - public static function deleteLike($name, $value = null) + public static function deleteLike($namePattern, $value = null) { - return self::getInstance()->deleteNameLike($name, $value); + return self::getInstance()->deleteNameLike($namePattern, $value); } /** - * Clears the cache - * Used in unit tests to reset the state of the object between tests + * Clears the option value cache and forces a reload from the Database. + * Used in unit tests to reset the state of the object between tests. * * @return void + * @ignore */ public static function clearCache() { @@ -191,5 +211,4 @@ class Option $this->loaded = true; } - -} +}
\ No newline at end of file |