From 42d790182824e36c0d20ed102dccf89292258e3c Mon Sep 17 00:00:00 2001 From: Pierre Goiffon Date: Wed, 11 Sep 2019 15:49:21 +0200 Subject: [PATCH] :art: some code formatting in utils class --- application/utils.inc.php | 189 ++++++++++++++++++++------------------ 1 file changed, 101 insertions(+), 88 deletions(-) diff --git a/application/utils.inc.php b/application/utils.inc.php index e2e7571a3a..9aba32ee0f 100644 --- a/application/utils.inc.php +++ b/application/utils.inc.php @@ -19,22 +19,6 @@ use ScssPhp\ScssPhp\Compiler; -// Copyright (C) 2010-2017 Combodo SARL -// -// This file is part of iTop. -// -// iTop is free software; you can redistribute it and/or modify -// it under the terms of the GNU Affero General Public License as published by -// the Free Software Foundation, either version 3 of the License, or -// (at your option) any later version. -// -// iTop is distributed in the hope that it will be useful, -// but WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -// GNU Affero General Public License for more details. -// -// You should have received a copy of the GNU Affero General Public License -// along with iTop. If not, see /** @@ -43,7 +27,6 @@ use ScssPhp\ScssPhp\Compiler; * @copyright Copyright (C) 2010-2017 Combodo SARL * @license http://opensource.org/licenses/AGPL-3.0 */ - require_once(APPROOT.'core/metamodel.class.php'); require_once(APPROOT.'core/config.class.inc.php'); require_once(APPROOT.'application/transaction.class.inc.php'); @@ -57,7 +40,6 @@ require_once(APPROOT.'application/logindefault.class.inc.php'); require_once(APPROOT.'application/loginexternal.class.inc.php'); require_once(APPROOT.'application/loginurl.class.inc.php'); - define('ITOP_CONFIG_FILE', 'config-itop.php'); define('ITOP_DEFAULT_CONFIG_FILE', APPCONF.ITOP_DEFAULT_ENV.'/'.ITOP_CONFIG_FILE); @@ -143,10 +125,10 @@ class utils /** * Return the source file from which the parameter has been found, - * usefull when it comes to pass user credential to a process executed - * in the background - * @param $sName Parameter name - * @return The file name if any, or null + * useful when it comes to pass user credential to a process executed + * in the background + * @param string $sName Parameter name + * @return string|null The file name if any, or null */ public static function GetParamSourceFile($sName) { @@ -391,13 +373,16 @@ class utils return $retValue; } - + /** * Reads an uploaded file and turns it into an ormDocument object - Triggers an exception in case of error - * @param string $sName Name of the input used from uploading the file - * @param string $sIndex If Name is an array of posted files, then the index must be used to point out the file + * + * @param string $sName Name of the input used from uploading the file + * @param string $sIndex If Name is an array of posted files, then the index must be used to point out the file + * * @return ormDocument The uploaded file (can be 'empty' if nothing was uploaded) - */ + * @throws \FileUploadException + */ public static function ReadPostedDocument($sName, $sIndex = null) { $oDocument = new ormDocument(); // an empty document @@ -452,14 +437,17 @@ class utils } return $oDocument; } - + /** * Interprets the results posted by a normal or paginated list (in multiple selection mode) * - * @param $oFullSetFilter DBSearch The criteria defining the whole sets of objects being selected + * @param DBSearch $oFullSetFilter The criteria defining the whole sets of objects being selected * - * @return Array An array of object IDs corresponding to the objects selected in the set - */ + * @return array An array of object IDs corresponding to the objects selected in the set + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MySQLException + */ public static function ReadMultipleSelection($oFullSetFilter) { $aSelectedObj = utils::ReadParam('selectObject', array()); @@ -553,11 +541,11 @@ class utils } /** - * Returns a unique tmp id for the current upload based on the transaction system (db). - * * Build as static::GetNewTransactionId() * - * @return string + * @param string $sTransactionId + * + * @return string unique tmp id for the current upload based on the transaction system (db). Build as static::GetNewTransactionId() */ public static function GetUploadTempId($sTransactionId = null) { @@ -579,7 +567,7 @@ class utils * as in php.ini, e.g. 256k, 2M, 1G etc. Into a number of bytes * @param mixed $value The value as read from php.ini * @return number - */ + */ public static function ConvertToBytes( $value ) { $iReturn = $value; @@ -616,7 +604,7 @@ class utils /** * Format a value into a more friendly format (KB, MB, GB, TB) instead a juste a Bytes amount. * - * @param type $value + * @param float $value * @return string */ public static function BytesToFriendlyFormat($value) @@ -657,8 +645,8 @@ class utils * Example: StringToTime('01/05/11 12:03:45', '%d/%m/%y %H:%i:%s') * @param string $sDate * @param string $sFormat - * @return timestamp or false if the input format is not correct - */ + * @return string|false false if the input format is not correct, timestamp otherwise + */ public static function StringToTime($sDate, $sFormat) { // Source: http://php.net/manual/fr/function.strftime.php @@ -700,12 +688,12 @@ class utils } /** - * Convert an old date/time format specifciation (using % placeholders) + * Convert an old date/time format specification (using % placeholders) * to a format compatible with DateTime::createFromFormat * @param string $sOldDateTimeFormat * @return string */ - static public function DateTimeFormatToPHP($sOldDateTimeFormat) + public static function DateTimeFormatToPHP($sOldDateTimeFormat) { $aSearch = array('%d', '%m', '%y', '%Y', '%H', '%i', '%s'); $aReplacement = array('d', 'm', 'y', 'Y', 'H', 'i', 's'); @@ -713,8 +701,8 @@ class utils } /** + * Allow to set cached config. Useful when running with {@link Parameters} for example. * @param \Config $oConfig - * */ public static function SetConfig(Config $oConfig) { @@ -789,7 +777,7 @@ class utils * * @throws \Exception */ - static public function GetAbsoluteUrlAppRoot() + public static function GetAbsoluteUrlAppRoot() { static $sUrl = null; if ($sUrl === null) @@ -824,7 +812,7 @@ class utils * * @throws \Exception */ - static public function GetDefaultUrlAppRoot() + public static function GetDefaultUrlAppRoot() { // Build an absolute URL to this page on this server/port $sServerName = isset($_SERVER['SERVER_NAME']) ? $_SERVER['SERVER_NAME'] : ''; @@ -899,7 +887,7 @@ class utils * nginx set it to an empty string * Others might leave it unset (no array entry) */ - static public function IsConnectionSecure() + public static function IsConnectionSecure() { $bSecured = false; @@ -954,10 +942,16 @@ class utils * @param string $sScript Name and relative path to the file (relative to the iTop root dir) * @param hash $aArguments Associative array of 'arg' => 'value' * @return array(iCode, array(output lines)) - */ - /** */ - static function ExecITopScript($sScriptName, $aArguments) + /** + * @param string $sScriptName + * @param array $aArguments + * + * @return array + * @throws \ConfigException + * @throws \CoreException + */ + public static function ExecITopScript($sScriptName, $aArguments) { $aDisabled = explode(', ', ini_get('disable_functions')); if (in_array('exec', $aDisabled)) @@ -1042,25 +1036,33 @@ class utils } /** - * Returns a path to a folder into which any module can store cache data + * @return string A path to a folder into which any module can store cache data * The corresponding folder is created or cleaned upon code compilation - * @return string */ public static function GetCachePath() { return APPROOT.'data/cache-'.MetaModel::GetEnvironment().'/'; } /** - * Returns a path to a folder into which any module can store log - * @return string + * @return string A path to a folder into which any module can store log * @since 2.7.0 */ public static function GetLogPath() { return APPROOT.'log/'; } + /** * Merge standard menu items with plugin provided menus items + * + * @param \WebPage $oPage + * @param int $iMenuId + * @param \DBObjectSet $param + * @param array $aActions + * @param string $sTableId + * @param string $sDataTableId + * + * @throws \Exception */ public static function GetPopupMenuItems($oPage, $iMenuId, $param, &$aActions, $sTableId = null, $sDataTableId = null) { @@ -1190,7 +1192,10 @@ class utils } } } + /** + * @param string $sEnvironment + * * @return string target configuration file name (including full path) */ public static function GetConfigFilePath($sEnvironment = null) @@ -1201,7 +1206,10 @@ class utils } return APPCONF.$sEnvironment.'/'.ITOP_CONFIG_FILE; } + /** + * @param string $sEnvironment + * * @return string target configuration file name (including relative path) */ public static function GetConfigFilePathRelative($sEnvironment = null) @@ -1213,10 +1221,11 @@ class utils return "conf/".$sEnvironment.'/'.ITOP_CONFIG_FILE; } - /** - * @return string the absolute URL to the modules root path - */ - static public function GetAbsoluteUrlModulesRoot() + /** + * @return string the absolute URL to the modules root path + * @throws \Exception + */ + public static function GetAbsoluteUrlModulesRoot() { $sUrl = self::GetAbsoluteUrlAppRoot().'env-'.self::GetCurrentEnvironment().'/'; return $sUrl; @@ -1231,17 +1240,20 @@ class utils * require_once(__DIR__.'/../../approot.inc.php'); * ``` * - * @param string $sModule - * @param string $sPage + * @see GetExecPageArguments can be used to submit using the GET method (see bug in N.1108) + * @see GetAbsoluteUrlExecPage + * * @param string[] $aArguments * @param string $sEnvironment * + * @param string $sModule + * @param string $sPage + * * @return string the URL to a page that will execute the requested module page, with query string values url encoded * - * @see GetExecPageArguments can be used to submit using the GET method (see bug in N.1108) - * @see GetAbsoluteUrlExecPage + * @throws \Exception */ - static public function GetAbsoluteUrlModulePage($sModule, $sPage, $aArguments = array(), $sEnvironment = null) + public static function GetAbsoluteUrlModulePage($sModule, $sPage, $aArguments = array(), $sEnvironment = null) { $aArgs = self::GetExecPageArguments($sModule, $sPage, $aArguments, $sEnvironment); $sArgs = http_build_query($aArgs); @@ -1258,7 +1270,7 @@ class utils * @return string[] key/value pair for the exec page query string. Warning : values are not url encoded ! * @throws \Exception if one of the argument has a reserved name */ - static public function GetExecPageArguments($sModule, $sPage, $aArguments = array(), $sEnvironment = null) + public static function GetExecPageArguments($sModule, $sPage, $aArguments = array(), $sEnvironment = null) { $sEnvironment = is_null($sEnvironment) ? self::GetCurrentEnvironment() : $sEnvironment; $aArgs = array(); @@ -1279,18 +1291,20 @@ class utils /** * @return string + * @throws \Exception */ - static public function GetAbsoluteUrlExecPage() + public static function GetAbsoluteUrlExecPage() { return self::GetAbsoluteUrlAppRoot().'pages/exec.php'; } /** - * Returns a name unique amongst the given list * @param string $sProposed The default value - * @param array $aExisting An array of existing values (strings) + * @param array $aExisting An array of existing values (strings) + * + * @return string a unique name amongst the given list */ - static public function MakeUniqueName($sProposed, $aExisting) + public static function MakeUniqueName($sProposed, $aExisting) { if (in_array($sProposed, $aExisting)) { @@ -1312,7 +1326,7 @@ class utils * @param string $sId The ID to sanitize * @return string The sanitized ID */ - static public function GetSafeId($sId) + public static function GetSafeId($sId) { return str_replace(array(':', '[', ']', '+', '-'), '_', $sId); } @@ -1334,7 +1348,7 @@ class utils * @return string The result of the POST request * @throws Exception with a specific error message depending on the cause */ - static public function DoPostRequest($sUrl, $aData, $sOptionnalHeaders = null, &$aResponseHeaders = null, $aCurlOptions = array()) + public static function DoPostRequest($sUrl, $aData, $sOptionnalHeaders = null, &$aResponseHeaders = null, $aCurlOptions = array()) { // $sOptionnalHeaders is a string containing additional HTTP headers that you would like to send in your request. @@ -1477,7 +1491,7 @@ class utils * @param string $sValue * @return string */ - static public function HtmlEntities($sValue) + public static function HtmlEntities($sValue) { return htmlentities($sValue, ENT_QUOTES, 'UTF-8'); } @@ -1520,7 +1534,7 @@ class utils * @param array $aImportPaths Array of absolute paths to load imports from * @return string Relative path to the CSS file (.css) */ - static public function GetCSSFromSASS($sSassRelPath, $aImportPaths = null) + public static function GetCSSFromSASS($sSassRelPath, $aImportPaths = null) { // Avoiding compilation if file is already a css file. if (preg_match('/\.css(\?.*)?$/', $sSassRelPath)) @@ -1554,7 +1568,7 @@ class utils return $sCssRelPath; } - static public function GetImageSize($sImageData) + public static function GetImageSize($sImageData) { if (function_exists('getimagesizefromstring')) // PHP 5.4.0 or higher { @@ -1677,7 +1691,7 @@ class utils * @param string $sPrefix * @return string */ - static public function CreateUUID($sPrefix = '') + public static function CreateUUID($sPrefix = '') { $uid = uniqid("", true); $data = $sPrefix; @@ -1701,10 +1715,10 @@ class utils /** * Returns the name of the module containing the file where the call to this function is made * or an empty string if no such module is found (or not called within a module file) - * @param number $iCallDepth The depth of the module in the callstack. Zero when called directly from within the module + * @param int $iCallDepth The depth of the module in the callstack. Zero when called directly from within the module * @return string */ - static public function GetCurrentModuleName($iCallDepth = 0) + public static function GetCurrentModuleName($iCallDepth = 0) { $sCurrentModuleName = ''; $aCallStack = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS); @@ -1733,7 +1747,7 @@ class utils * @param number $iCallDepth The depth of the module in the callstack. Zero when called directly from within the module * @return string */ - static public function GetCurrentModuleDir($iCallDepth) + public static function GetCurrentModuleDir($iCallDepth) { $sCurrentModuleDir = ''; $aCallStack = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS); @@ -1754,13 +1768,13 @@ class utils } return $sCurrentModuleDir; } - + /** - * Returns the base URL for all files in the current module from which this method is called + * @return string the base URL for all files in the current module from which this method is called * or an empty string if no such module is found (or not called within a module file) - * @return string + * @throws \Exception */ - static public function GetCurrentModuleUrl() + public static function GetCurrentModuleUrl() { $sDir = static::GetCurrentModuleDir(1); if ( $sDir !== '') @@ -1771,23 +1785,21 @@ class utils } /** - * Get the value of a given setting for the current module * @param string $sProperty The name of the property to retrieve * @param mixed $defaultvalue - * @return mixed + * @return mixed the value of a given setting for the current module */ - static public function GetCurrentModuleSetting($sProperty, $defaultvalue = null) + public static function GetCurrentModuleSetting($sProperty, $defaultvalue = null) { $sModuleName = static::GetCurrentModuleName(1); return MetaModel::GetModuleSetting($sModuleName, $sProperty, $defaultvalue); } /** - * Get the compiled version of a given module, as it was seen by the compiler * @param string $sModuleName - * @return string|NULL + * @return string|NULL compiled version of a given module, as it was seen by the compiler */ - static public function GetCompiledModuleVersion($sModuleName) + public static function GetCompiledModuleVersion($sModuleName) { $aModulesInfo = GetModulesInfo(); if (array_key_exists($sModuleName, $aModulesInfo)) @@ -2001,10 +2013,9 @@ class utils } /** - * Return a string based on compilation time or (if not available because the datamodel has not been loaded) + * @return string a string based on compilation time or (if not available because the datamodel has not been loaded) * the version of iTop. This string is useful to prevent browser side caching of content that may vary at each - * (re)installation of iTop (especially during development). - * @return string + * (re)installation of iTop (especially during development). */ public static function GetCacheBusterTimestamp() { @@ -2021,6 +2032,8 @@ class utils * @param $sClass * * @return bool + * @throws \ConfigException + * @throws \CoreException */ public static function IsHighCardinality($sClass) { @@ -2083,7 +2096,7 @@ class utils * * @return bool */ - public final static function StartsWith($haystack, $needle) + final public static function StartsWith($haystack, $needle) { return substr_compare($haystack, $needle, 0, strlen($needle)) === 0; } @@ -2095,7 +2108,7 @@ class utils * * @return bool */ - public final static function EndsWith($haystack, $needle) { + final public static function EndsWith($haystack, $needle) { return substr_compare($haystack, $needle, -strlen($needle)) === 0; } }