Refs #4200, do not generate docs for CacheFile class, document @api methods in Common, remove unused Common:: var, remove Common::substr and Common::strlen.

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 '&lt;'
-     *         - '>' (greater than) becomes '&gt;'
-     * - 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);