diff options
-rw-r--r-- | core/Archive.php | 6 | ||||
-rw-r--r-- | core/CacheFile.php | 1 | ||||
-rw-r--r-- | core/Common.php | 193 | ||||
-rw-r--r-- | core/Http.php | 8 | ||||
-rw-r--r-- | core/IP.php | 14 | ||||
-rw-r--r-- | core/Tracker/Visit.php | 2 | ||||
-rw-r--r-- | core/Url.php | 2 | ||||
-rw-r--r-- | plugins/AnonymizeIP/AnonymizeIP.php | 2 | ||||
-rwxr-xr-x | tests/PHPUnit/BenchmarkTestCase.php | 1 | ||||
-rwxr-xr-x | tests/PHPUnit/Benchmarks/Fixtures/SqlDump.php | 1 |
10 files changed, 112 insertions, 118 deletions
diff --git a/core/Archive.php b/core/Archive.php index 0ba82cc81f..24a650bde5 100644 --- a/core/Archive.php +++ b/core/Archive.php @@ -18,9 +18,9 @@ use Piwik\Period\Range; /** * The **Archive** class is used to query archive data. - * @see Segment - * You can use **Archive** instances to get archive data for one or more sites and - * for one or more periods. A Segment can also be used + * + * You can use **Archive** instances to get archive data for one or more sites, + * for one or more periods and on optional segment. * * If archive data is not found, this class will initiate the archiving process. [1](#footnote-1) * diff --git a/core/CacheFile.php b/core/CacheFile.php index 7efa65309a..9443cbc96f 100644 --- a/core/CacheFile.php +++ b/core/CacheFile.php @@ -18,7 +18,6 @@ use Exception; * It is for example used by the Tracker process to cache various settings and websites attributes in tmp/cache/tracker/* * * @package Piwik - * @api */ class CacheFile { diff --git a/core/Common.php b/core/Common.php index 2d7a95e0b6..7a652b8425 100644 --- a/core/Common.php +++ b/core/Common.php @@ -56,14 +56,14 @@ class Common return base_convert($stringHash, 16, 10); } - public static $cachedTablePrefix = null; - /** - * Returns the table name prefixed by the table prefix. - * Works in both Tracker and UI mode. + * Returns a prefixed table name. + * + * The table prefix is determined by the `[database] tables_prefix` INI config + * option. * * @param string $table The table name to prefix, ie "log_visit" - * @return string The table name prefixed, ie "piwik-production_log_visit" + * @return string The prefixed name, ie "piwik-production_log_visit". * @api */ public static function prefixTable($table) @@ -88,10 +88,13 @@ class Common } /** - * Returns the table name, after removing the table prefix + * Removes the prefix from a table name and returns the result. * - * @param string $table - * @return string + * The table prefix is determined by the `[database] tables_prefix` INI config + * option. + * + * @param string $table The prefixed table name, eg "piwik-production_log_visit". + * @return string The unprefixed table name, eg "log_visit". * @api */ public static function unprefixTable($table) @@ -136,45 +139,15 @@ class Common */ /** - * byte-oriented substr() - ASCII - * - * @param string $string - * @param int $start - * @param int ... optional length - * @return string - */ - public static function substr($string, $start) - { - // in case mbstring overloads substr function - $substr = function_exists('mb_orig_substr') ? 'mb_orig_substr' : 'substr'; - - $length = func_num_args() > 2 - ? func_get_arg(2) - : self::strlen($string); - - return $substr($string, $start, $length); - } - - /** - * byte-oriented strlen() - ASCII - * - * @param string $string - * @return int - */ - public static function strlen($string) - { - // in case mbstring overloads strlen function - $strlen = function_exists('mb_orig_strlen') ? 'mb_orig_strlen' : 'strlen'; - return $strlen($string); - } - - /** - * multi-byte substr() - UTF-8 + * Multi-byte substr() - works with UTF-8. + * + * Calls `mb_substr` if available and falls back to `substr` if it's not. * * @param string $string * @param int $start * @param int ... optional length * @return string + * @api */ public static function mb_substr($string, $start) { @@ -190,10 +163,13 @@ class Common } /** - * multi-byte strlen() - UTF-8 + * Multi-byte strlen() - works with UTF-8 + * + * Calls `mb_substr` if available and falls back to `substr` if not. * * @param string $string * @return int + * @api */ public static function mb_strlen($string) { @@ -205,10 +181,13 @@ class Common } /** - * multi-byte strtolower() - UTF-8 - * + * Multi-byte strtolower() - works with UTF-8. + * + * Calls `mb_strtolower` if available and falls back to `strtolower` if not. + * * @param string $string * @return string + * @api */ public static function mb_strtolower($string) { @@ -224,28 +203,32 @@ class Common */ /** - * Returns the variable after cleaning operations. - * NB: The variable still has to be escaped before going into a SQL Query! - * - * If an array is passed the cleaning is done recursively on all the sub-arrays. - * The array's keys are filtered as well! - * - * How this method works: - * - The variable returned has been htmlspecialchars to avoid the XSS security problem. - * - The single quotes are not protected so "Piwik's amazing" will still be "Piwik's amazing". - * - * - Transformations are: - * - '&' (ampersand) becomes '&' - * - '"'(double quote) becomes '"' - * - '<' (less than) becomes '<' - * - '>' (greater than) becomes '>' - * - It handles the magic_quotes setting. - * - A non string value is returned without modification - * - * @param mixed $value The variable to be cleaned + * Sanitizes a string to help avoid XSS vulnerabilities. + * + * This function is automatically called when [getRequestVar](#getRequestVar) is called, + * so you should not normally have to use it. + * + * You should used it when outputting data that isn't escaped and was + * obtained from the user (for example when using the `|raw` twig filter on goal names). + * + * NOTE: Sanitized input should not be used directly in an SQL query; SQL placeholders + * should still be used. + * + * **Implementation Details** + * + * - `htmlspecialchars` is used to escape text. + * - Single quotes are not escaped so "Piwik's amazing community" will still be + * "Piwik's amazing community". + * - Use of the `magic_quotes` setting will not break this method. + * - Boolean, numeric and null values are simply returned. + * + * @param mixed $value The variable to be cleaned. If an array is supplied, the contents + * of the array will be sanitized recursively. The keys of the array + * will also be sanitized. * @param bool $alreadyStripslashed - * @throws Exception - * @return mixed The variable after cleaning + * @throws Exception If `$value` is of an incorrect type. + * @return mixed The sanitized value. + * @api */ public static function sanitizeInputValues($value, $alreadyStripslashed = false) { @@ -306,8 +289,8 @@ class Common } /** - * Unsanitize a single input value - * + * Unsanitizes a single input value and returns the result. + * * @param string $value * @return string unsanitized input */ @@ -317,10 +300,18 @@ class Common } /** - * Unsanitize one or more values. + * Unsanitizes one or more values and returns the result. * - * @param string|array $value - * @return string|array unsanitized input + * This method should be used when you need to unescape data that was obtained from + * the user. + * + * Some data in Piwik is stored sanitized (such as site name). In this case you may + * have to use this method to unsanitize it after it is retrieved. + * + * @param string|array $value The data to unsanitize. If an array is passed the + * array is sanitized recursively. Keys are not unsanitized. + * @return string|array The unsanitized data. + * @api */ public static function unsanitizeInputValues($value) { @@ -344,7 +335,7 @@ class Common private static function undoMagicQuotes($value) { return version_compare(PHP_VERSION, '5.4', '<') - && get_magic_quotes_gpc() + && get_magic_quotes_gpc() ? stripslashes($value) : $value; } @@ -361,21 +352,24 @@ class Common } /** - * Returns a sanitized variable value from the $_GET and $_POST superglobal. - * If the variable doesn't have a value or an empty value, returns the defaultValue if specified. + * Gets a sanitized request parameter by name from the `$_GET` and `$_POST` superglobals. + * + * Use this function to get request parameter values. **_NEVER use `$_GET` and `$_POST` directly._** + * * If the variable doesn't have neither a value nor a default value provided, an exception is raised. * * @see sanitizeInputValues() for the applied sanitization * - * @param string $varName name of the variable - * @param string $varDefault default value. If '', and if the type doesn't match, exit() ! - * @param string $varType Expected type, the value must be one of the following: array, int, integer, string, json - * @param array $requestArrayToUse - * - * @throws Exception if the variable type is not known - * or if the variable we want to read doesn't have neither a value nor a default value specified - * - * @return mixed The variable after cleaning + * @param string $varName Name of the request parameter to get. We look in `$_GET[$varName]` and `$_POST[$varName]` + * for the value. + * @param string|null $varDefault The value to return if the request parameter doesn't exist or has an empty value. + * @param string|null $varType Expected type, the value must be one of the following: `'array'`, `'int'`, `'integer'`, + * `'string'`, `'json'`. If `'json'`, the string value will be `json_decode`-d and all of + * entries sanitized. + * @param array|null $requestArrayToUse The array to use instead of $_GET and $_POST. + * @throws Exception If the request parameter doesn't exist and there is no default value or if the request parameter + * exists but has an incorrect type. + * @return mixed The sanitized request parameter. * @api */ public static function getRequestVar($varName, $varDefault = null, $varType = null, $requestArrayToUse = null) @@ -576,7 +570,7 @@ class Common * * @param mixed $value * @return string - * @api + * @deprecated */ public static function json_encode($value) { @@ -590,7 +584,7 @@ class Common * @param string $json * @param bool $assoc * @return mixed - * @api + * @deprecated */ public static function json_decode($json, $assoc = false) { @@ -651,11 +645,12 @@ class Common } /** - * Returns list of valid language codes + * Returns the list of valid language codes. * * @see core/DataFiles/Languages.php * - * @return array Array of 2 letter ISO codes => Language name (in English) + * @return array Array of two letter ISO codes mapped with language name (in English). E.g. + * `array('en' => 'English')`. * @api */ public static function getLanguagesList() @@ -667,11 +662,12 @@ class Common } /** - * Returns list of language to country mappings + * Returns list of language to country mappings. * * @see core/DataFiles/LanguageToCountry.php * - * @return array Array of ( 2 letter ISO language codes => 2 letter ISO country codes ) + * @return array Array of two letter ISO language codes mapped with two letter ISO country codes: + * `array('fr' => 'fr'), // French => France` * @api */ public static function getLanguageToCountryList() @@ -911,11 +907,13 @@ class Common */ /** - * Takes a list of fields defining numeric values and returns the corresponding - * unnamed parameters to be bound to the field names in the where clause of a SQL query - * - * @param array|string $fields array( fieldName1, fieldName2, fieldName3) Names of the mysql table fields to load - * @return string "?, ?, ?" + * Returns a string with a comma separated list of placeholders for use in an SQL query based + * on the list of fields we're referencing. Used mainly to fill the `IN (...)` part of a query. + * + * @param array|string $fields The names of the mysql table fields to bind, e.g. + * `array(fieldName1, fieldName2, fieldName3)`. + * @return string The placeholder string, e.g. `"?, ?, ?"`. + * @api */ public static function getSqlStringFieldsArray($fields) { @@ -957,10 +955,11 @@ class Common } /** - * Mark orphaned object for garbage collection + * Mark orphaned object for garbage collection. * * For more information: @link http://dev.piwik.org/trac/ticket/374 * @param $var + * @api */ static public function destroy(&$var) { @@ -983,6 +982,4 @@ class Common } } } - -} - +}
\ No newline at end of file diff --git a/core/Http.php b/core/Http.php index 06feff3706..65be4de797 100644 --- a/core/Http.php +++ b/core/Http.php @@ -338,7 +338,7 @@ class Http throw new Exception('Timed out waiting for server response'); } - $fileLength += Common::strlen($line); + $fileLength += strlen($line); if (is_resource($file)) { // save to file @@ -390,13 +390,13 @@ class Http $handle = fopen($aUrl, 'rb', false, $ctx); while (!feof($handle)) { $response = fread($handle, 8192); - $fileLength += Common::strlen($response); + $fileLength += strlen($response); fwrite($file, $response); } fclose($handle); } else { $response = file_get_contents($aUrl, 0, $ctx); - $fileLength = Common::strlen($response); + $fileLength = strlen($response); } // restore the socket_timeout value @@ -497,7 +497,7 @@ class Http } $contentLength = @curl_getinfo($ch, CURLINFO_CONTENT_LENGTH_DOWNLOAD); - $fileLength = is_resource($file) ? @curl_getinfo($ch, CURLINFO_SIZE_DOWNLOAD) : Common::strlen($response); + $fileLength = is_resource($file) ? @curl_getinfo($ch, CURLINFO_SIZE_DOWNLOAD) : strlen($response); $status = @curl_getinfo($ch, CURLINFO_HTTP_CODE); @curl_close($ch); diff --git a/core/IP.php b/core/IP.php index 0b3d152ee7..df22099971 100644 --- a/core/IP.php +++ b/core/IP.php @@ -114,7 +114,7 @@ class IP if (($ip = @inet_pton($ipRangeString)) === false) return false; - $maxbits = Common::strlen($ip) * 8; + $maxbits = strlen($ip) * 8; if (!isset($bits)) $bits = $maxbits; @@ -207,17 +207,17 @@ class IP public static function long2ip($ip) { // IPv4 - if (Common::strlen($ip) == 4) { + if (strlen($ip) == 4) { return self::N2P($ip); } // IPv6 - transitional address? - if (Common::strlen($ip) == 16) { + if (strlen($ip) == 16) { if (substr_compare($ip, "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xff\xff", 0, 12) === 0 || substr_compare($ip, "\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00", 0, 12) === 0 ) { // remap 128-bit IPv4-mapped and IPv4-compat addresses - return self::N2P(Common::substr($ip, 12)); + return self::N2P(substr($ip, 12)); } } @@ -275,7 +275,7 @@ class IP return false; } - $lowLen = Common::strlen($low); + $lowLen = strlen($low); $i = $lowLen - 1; $bits = $lowLen * 8 - $bits; @@ -304,7 +304,7 @@ class IP */ public static function isIpInRange($ip, $ipRanges) { - $ipLen = Common::strlen($ip); + $ipLen = strlen($ip); if (empty($ip) || empty($ipRanges) || ($ipLen != 4 && $ipLen != 16)) { return false; } @@ -324,7 +324,7 @@ class IP $low = $range[0]; $high = $range[1]; - if (Common::strlen($low) != $ipLen) { + if (strlen($low) != $ipLen) { continue; } diff --git a/core/Tracker/Visit.php b/core/Tracker/Visit.php index a28af3c193..b2b8b6d4ef 100644 --- a/core/Tracker/Visit.php +++ b/core/Tracker/Visit.php @@ -946,7 +946,7 @@ class Visit implements VisitInterface protected function getConfigHash($os, $browserName, $browserVersion, $plugin_Flash, $plugin_Java, $plugin_Director, $plugin_Quicktime, $plugin_RealPlayer, $plugin_PDF, $plugin_WindowsMedia, $plugin_Gears, $plugin_Silverlight, $plugin_Cookie, $ip, $browserLang) { $hash = md5($os . $browserName . $browserVersion . $plugin_Flash . $plugin_Java . $plugin_Director . $plugin_Quicktime . $plugin_RealPlayer . $plugin_PDF . $plugin_WindowsMedia . $plugin_Gears . $plugin_Silverlight . $plugin_Cookie . $ip . $browserLang, $raw_output = true); - return Common::substr($hash, 0, Tracker::LENGTH_BINARY_ID); + return substr($hash, 0, Tracker::LENGTH_BINARY_ID); } /** diff --git a/core/Url.php b/core/Url.php index ff38faff9c..9472d3edde 100644 --- a/core/Url.php +++ b/core/Url.php @@ -198,7 +198,7 @@ class Url } // Only punctuation we allow is '[', ']', ':', '.' and '-' - $hostLength = Common::strlen($host); + $hostLength = strlen($host); if ($hostLength !== strcspn($host, '`~!@#$%^&*()_+={}\\|;"\'<>,?/ ')) { return false; } diff --git a/plugins/AnonymizeIP/AnonymizeIP.php b/plugins/AnonymizeIP/AnonymizeIP.php index 0fe17f0cb0..bdd4856ab8 100644 --- a/plugins/AnonymizeIP/AnonymizeIP.php +++ b/plugins/AnonymizeIP/AnonymizeIP.php @@ -57,7 +57,7 @@ class AnonymizeIP extends \Piwik\Plugin { // IPv4 or mapped IPv4 in IPv6 if (IP::isIPv4($ip)) { - $i = Common::strlen($ip); + $i = strlen($ip); if ($maskLength > $i) { $maskLength = $i; } diff --git a/tests/PHPUnit/BenchmarkTestCase.php b/tests/PHPUnit/BenchmarkTestCase.php index 2152ccb583..9e26527b31 100755 --- a/tests/PHPUnit/BenchmarkTestCase.php +++ b/tests/PHPUnit/BenchmarkTestCase.php @@ -49,7 +49,6 @@ abstract class BenchmarkTestCase extends IntegrationTestCase try { if (isset(self::$fixture->tablesPrefix)) { Config::getInstance()->database['tables_prefix'] = self::$fixture->tablesPrefix; - Common::$cachedTablePrefix = null; } Db::query("USE " . $dbName); diff --git a/tests/PHPUnit/Benchmarks/Fixtures/SqlDump.php b/tests/PHPUnit/Benchmarks/Fixtures/SqlDump.php index 19beb1011b..ddf2ff8f7e 100755 --- a/tests/PHPUnit/Benchmarks/Fixtures/SqlDump.php +++ b/tests/PHPUnit/Benchmarks/Fixtures/SqlDump.php @@ -62,7 +62,6 @@ class Piwik_Test_Fixture_SqlDump $password = Config::getInstance()->database['password']; $dbName = Config::getInstance()->database['dbname']; Config::getInstance()->database['tables_prefix'] = $this->tablesPrefix; - Common::$cachedTablePrefix = null; $cmd = "mysql -u \"$user\" \"--password=$password\" $dbName < \"" . $deflatedDumpPath . "\" 2>&1"; exec($cmd, $output, $return); |