Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

core(config) : Improve config class PHPDoc #3027

Open
wants to merge 1 commit into
base: alpha
Choose a base branch
from
Open

core(config) : Improve config class PHPDoc #3027

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
224 changes: 205 additions & 19 deletions core/class/config.class.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,33 @@
/* * ***************************Includes********************************* */
require_once __DIR__ . '/../../core/php/core.inc.php';

/**
* Manages Jeedom configuration system
* @see jeedom
*/
class config {
/* * *************************Attributs****************************** */

/** @var array<string, array<string, array<string, mixed>>> Default configuration values */
private static $defaultConfiguration = array();

/** @var array<string, mixed> Configuration cache */
private static $cache = array();

/** @var string[] List of configuration keys to encrypt */
private static $encryptKey = array('apipro', 'apitts', 'apimarket', 'samba::backup::password', 'samba::backup::ip', 'samba::backup::username', 'ldap:password', 'ldap:host', 'ldap:username', 'dns::token', 'api');
private static $nocache = array('enableScenario');

/** @var string[] Configuration keys that should not be cached */
private static $nocache = array('enableScenario');

/* * ***********************Methode static*************************** */

/**
* Gets default configuration for a plugin
*
* @param string $_plugin Plugin name
* @return array<string, array<string, mixed>> Default configuration
*/
public static function getDefaultConfiguration(string $_plugin = 'core') {
if (!isset(self::$defaultConfiguration[$_plugin])) {
if ($_plugin == 'core') {
Expand All @@ -49,13 +66,15 @@ public static function getDefaultConfiguration(string $_plugin = 'core') {
}
return self::$defaultConfiguration[$_plugin];
}
/**
* Save key to config
* @param string $_key
* @param string | object | array $_value
* @param string $_plugin
* @return boolean
*/

/**
* Saves a configuration value
*
* @param string $_key Configuration key
* @param mixed $_value Configuration value
* @param string $_plugin Plugin name
* @return bool Success status
*/
public static function save($_key, $_value, $_plugin = 'core') {
$class = ($_plugin == 'core') ? 'config' : $_plugin;
if (is_object($_value) || is_array($_value)) {
Expand Down Expand Up @@ -109,11 +128,13 @@ public static function save($_key, $_value, $_plugin = 'core') {
return true;
}

/**
* Delete key from config
* @param string $_key nom de la clef à supprimer
* @return boolean vrai si ok faux sinon
*/
/**
* Removes a configuration key
*
* @param string $_key Configuration key
* @param string $_plugin Plugin name
* @return bool Success status
*/
public static function remove(string $_key, string $_plugin = 'core') {
if ($_key == "*" && $_plugin != 'core') {
$values = array(
Expand Down Expand Up @@ -141,11 +162,15 @@ public static function remove(string $_key, string $_plugin = 'core') {
return true;
}

/**
* Get config by key
* @param string $_key nom de la clef dont on veut la valeur
* @return string valeur de la clef
*/
/**
* Gets configuration value by key
*
* @param string $_key Configuration key
* @param string $_plugin Plugin name
* @param mixed $_default Default value
* @param bool $_forceFresh Force cache refresh
* @return string|mixed Configuration value
*/
public static function byKey($_key, $_plugin = 'core', $_default = '', $_forceFresh = false) {
if (!$_forceFresh && isset(self::$cache[$_plugin . '::' . $_key]) && !in_array($_key, self::$nocache)) {
return self::$cache[$_plugin . '::' . $_key];
Expand Down Expand Up @@ -180,6 +205,15 @@ public static function byKey($_key, $_plugin = 'core', $_default = '', $_forceFr
return isset(self::$cache[$_plugin . '::' . $_key]) ? self::$cache[$_plugin . '::' . $_key] : '';
}

/**
* Gets multiple configuration values by keys
*
* @param array<string>|mixed $_keys Configuration keys
* @param string $_plugin Plugin name
* @param mixed $_default Default value
* @return array<string, mixed> Configuration values
* @throws Exception On error
*/
public static function byKeys($_keys, $_plugin = 'core', $_default = '') {
if (!is_array($_keys) || count($_keys) == 0) {
return array();
Expand Down Expand Up @@ -227,6 +261,14 @@ public static function byKeys($_keys, $_plugin = 'core', $_default = '') {
return $return;
}

/**
* Searches configuration by key pattern
*
* @param string $_key Key pattern to search
* @param string $_plugin Plugin name
* @return array<string, mixed>[] Matching configurations
* @throws Exception On error
*/
public static function searchKey($_key, $_plugin = 'core') {
$values = array(
'plugin' => $_plugin,
Expand All @@ -250,6 +292,13 @@ public static function searchKey($_key, $_plugin = 'core') {
return $results;
}

/**
* Generates a random key
*
* @param int $_car Key length
* @return string Generated key
* @throws \Random\RandomException On random generation error
*/
public static function genKey($_car = 64) {
if ($_car > 256) {
throw new \Exception('Key length too long');
Expand All @@ -266,6 +315,12 @@ public static function genKey($_car = 64) {
return $key;
}

/**
* Gets list of enabled plugins
*
* @return array<string, mixed> Enabled plugins
* @throws Exception On error
*/
public static function getPluginEnable() {
$sql = 'SELECT `value`,`plugin`
FROM config
Expand All @@ -278,6 +333,12 @@ public static function getPluginEnable() {
return $return;
}

/**
* Gets log levels by plugin
*
* @return array<string, mixed> Log levels
* @throws Exception On error
*/
public static function getLogLevelPlugin() {
$sql = 'SELECT `value`,`key`
FROM config
Expand All @@ -290,6 +351,12 @@ public static function getLogLevelPlugin() {
return $return;
}

/**
* Gets generic types configuration
*
* @param bool $_coreOnly Get only core types
* @return array<string, array<string, mixed>> Generic types
*/
public static function getGenericTypes($_coreOnly = false) {
$types = array(
'byType',
Expand Down Expand Up @@ -331,6 +398,14 @@ public static function getGenericTypes($_coreOnly = false) {

/* * *********************Generic check value************************* */

/**
* Ensures value is between bounds
*
* @param int|float|mixed $_value Value to check
* @param int|float|null $_min Minimum bound
* @param int|float|null $_max Maximum bound
* @return float|int|mixed Checked value
*/
public static function checkValueBetween($_value, $_min = null, $_max = null) {
if ($_min !== null && $_value < $_min) {
return $_min;
Expand All @@ -346,6 +421,13 @@ public static function checkValueBetween($_value, $_min = null, $_max = null) {

/* * *********************Action sur config************************* */

/**
* Handles DNS configuration changes
*
* @param int $_value New DNS allow status (0|1)
* @return void
* @throws Exception If DNS operation fails
*/
public static function postConfig_market_allowDns($_value) {
if ($_value == 1) {
if (!network::dns_run()) {
Expand All @@ -358,13 +440,32 @@ public static function postConfig_market_allowDns($_value) {
}
}

/**
* Updates day theme start hour
*
* @param string $_value Hour in format HH:mm
* @return void
*/
public static function postConfig_theme_start_day_hour($_value) {
event::add('checkThemechange', array('theme_start_day_hour' => $_value));
}

/**
* Updates day theme end hour
*
* @param string $_value Hour in format HH:mm
* @return void
*/
public static function postConfig_theme_end_day_hour($_value) {
event::add('checkThemechange', array('theme_end_day_hour' => $_value));
}

/**
* Refreshes object summaries after configuration change
*
* @param mixed $_value Not used
* @return void
*/
public static function postConfig_object_summary($_value) {
$events = array();
try {
Expand Down Expand Up @@ -406,53 +507,125 @@ public static function postConfig_object_summary($_value) {
}
}

/**
* Validates history archive package value
*
* @param int $_value Archive package count
* @return int Validated value (minimum 1)
*/
public static function preConfig_historyArchivePackage($_value) {
return self::checkValueBetween($_value, 1);
}

public static function preConfig_historyArchiveTime($_value) {
/**
* Validates history archive time value
*
* @param int $_value Archive time in days
* @return int Validated value (minimum 2)
*/
public static function preConfig_historyArchiveTime($_value) {
return self::checkValueBetween($_value, 2);
}

/**
* Ensures market password is hashed
*
* @param string $_value Password value
* @return string SHA1 hashed password
*/
public static function preConfig_market_password($_value) {
if (!is_sha1($_value)) {
return sha1($_value);
}
return $_value;
}

/**
* Validates widget margin value
*
* @param int $_value Margin in pixels
* @return int Validated value (minimum 0)
*/
public static function preConfig_widget_margin($_value) {
return self::checkValueBetween($_value, 0);
}

/**
* Validates widget width step value
*
* @param int $_value Width step in pixels
* @return int Validated value (minimum 1)
*/
public static function preConfig_widget_step_width($_value) {
return self::checkValueBetween($_value, 1);
}

/**
* Validates widget height step value
*
* @param int $_value Height step in pixels
* @return int Validated value (minimum 1)
*/
public static function preConfig_widget_step_height($_value) {
return self::checkValueBetween($_value, 1);
}

/**
* Validates background opacity value
*
* @param float $_value Opacity value
* @return float Validated value (between 0 and 1)
*/
public static function preConfig_css_background_opacity($_value) {
return self::checkValueBetween($_value, 0, 1);
}

/**
* Validates border radius value
*
* @param float $_value Border radius value
* @return float Validated value (between 0 and 1)
*/
public static function preConfig_css_border_radius($_value) {
return self::checkValueBetween($_value, 0, 1);
}

/**
* Sanitizes name value
*
* @param string $_value Raw name
* @return string Sanitized name (removed special chars)
*/
public static function preConfig_name($_value) {
return str_replace(array('\\', '/', "'", '"'), '', $_value);
}

/**
* Formats latitude value
*
* @param string $_value Raw latitude
* @return string Formatted latitude (decimal format)
*/
public static function preConfig_info_latitude($_value) {
return trim(str_replace(',', '.', $_value));
}

/**
* Formats longitude value
*
* @param string $_value Raw longitude
* @return string Formatted longitude (decimal format)
*/
public static function preConfig_info_longitude($_value) {
return trim(str_replace(',', '.', $_value));
}

/**
* Updates TTS engine configuration
*
* @param string $_value Engine identifier
* @return string Validated engine identifier
*/
public static function preConfig_tts_engine($_value) {
try {
if ($_value != config::byKey('tts::engine')) {
Expand All @@ -464,12 +637,25 @@ public static function preConfig_tts_engine($_value) {
}

/* * *********************Stats************************************* */

/**
* Gets number of historized commands
*
* @return int Number of commands
* @throws Exception On error
*/
public static function getHistorizedCmdNum() {
$sql = 'SELECT COUNT(*) FROM `cmd` WHERE `isHistorized` = 1';
$result = DB::Prepare($sql, array(), DB::FETCH_TYPE_ALL);
return $result[0]['COUNT(*)'];
}

/**
* Gets number of timelined commands
*
* @return int Number of commands
* @throws Exception On error
*/
public static function getTimelinedCmdNum() {
$sql = 'SELECT COUNT(*) FROM `cmd` WHERE `configuration` LIKE \'%"timeline::enable":"1"%\'';
$result = DB::Prepare($sql, array(), DB::FETCH_TYPE_ALL);
Expand Down