diff options
43 files changed, 1091 insertions, 665 deletions
diff --git a/core/API/Proxy.php b/core/API/Proxy.php index a50a2228ac..9964406ea0 100644 --- a/core/API/Proxy.php +++ b/core/API/Proxy.php @@ -40,7 +40,15 @@ class Piwik_API_Proxy // when a parameter doesn't have a default value we use this private $noDefaultValue; + /** + * Singleton instance + * @var self|null + */ static private $instance = null; + + /** + * protected constructor + */ protected function __construct() { $this->noDefaultValue = new Piwik_API_Proxy_NoDefaultValue(); @@ -82,7 +90,7 @@ class Piwik_API_Proxy * * The method will introspect the methods, their parameters, etc. * - * @param string ModuleName eg. "Piwik_UserSettings_API" + * @param string $className ModuleName eg. "Piwik_UserSettings_API" */ public function registerClass( $className ) { @@ -105,8 +113,9 @@ class Piwik_API_Proxy /** * Will be displayed in the API page - * @param $rClass - * @param $className + * + * @param ReflectionClass $rClass Instance of ReflectionClass + * @param string $className Name of the class */ private function setDocumentation($rClass, $className) { @@ -142,9 +151,9 @@ class Piwik_API_Proxy * It also logs the API calls, with the parameters values, the returned value, the performance, etc. * You can enable logging in config/global.ini.php (log_api_call) * - * @param string $className The class name (eg. Piwik_Referers_API) - * @param string $methodName The method name - * @param array $parametersRequest The parameters pairs (name=>value) + * @param string $className The class name (eg. Piwik_Referers_API) + * @param string $methodName The method name + * @param array $parametersRequest The parameters pairs (name=>value) * * @return mixed|null * @throws Exception|Piwik_Access_NoAccessException @@ -220,13 +229,13 @@ class Piwik_API_Proxy * Returns the parameters names and default values for the method $name * of the class $class * - * @param string The class name - * @param string The method name - * @return array Format array( - * 'testParameter' => null, // no default value - * 'life' => 42, // default value = 42 - * 'date' => 'yesterday', - * ); + * @param string $class The class name + * @param string $name The method name + * @return array Format array( + * 'testParameter' => null, // no default value + * 'life' => 42, // default value = 42 + * 'date' => 'yesterday', + * ); */ public function getParametersList($class, $name) { @@ -234,8 +243,9 @@ class Piwik_API_Proxy } /** - * Returns the 'moduleName' part of 'Piwik_moduleName_API' classname - * @param string "Piwik_Referers_API" + * Returns the 'moduleName' part of 'Piwik_moduleName_API' classname + * + * @param string $className "Piwik_Referers_API" * @return string "Referers" */ public function getModuleNameFromClassName( $className ) @@ -246,8 +256,8 @@ class Piwik_API_Proxy /** * Returns an array containing the values of the parameters to pass to the method to call * - * @param array $requiredParameters array of (parameter name, default value) - * @param array $parametersRequest + * @param array $requiredParameters array of (parameter name, default value) + * @param array $parametersRequest * @throws Exception * @return array values to pass to the function call */ @@ -285,11 +295,12 @@ class Piwik_API_Proxy } return $finalParameters; } - + /** * Includes the class Piwik_UserSettings_API by looking up plugins/UserSettings/API.php * - * @param string api class name eg. "Piwik_UserSettings_API" + * @param string $fileName api class name eg. "Piwik_UserSettings_API" + * @throws Exception */ private function includeApiFile($fileName) { @@ -306,6 +317,10 @@ class Piwik_API_Proxy } } + /** + * @param string $class name of a class + * @param ReflectionMethod $method instance of ReflectionMethod + */ private function loadMethodMetadata($class, $method) { if($method->isPublic() @@ -339,9 +354,9 @@ class Piwik_API_Proxy /** * Checks that the method exists in the class * - * @param string The class name - * @param string The method name - * @throws exception If the method is not found + * @param string $className The class name + * @param string $methodName The method name + * @throws Exception If the method is not found */ private function checkMethodExists($className, $methodName) { @@ -354,8 +369,8 @@ class Piwik_API_Proxy /** * Returns the number of required parameters (parameters without default values). * - * @param string The class name - * @param string The method name + * @param string $class The class name + * @param string $name The method name * @return int The number of required parameters */ private function getNumberOfRequiredParameters($class, $name) @@ -366,8 +381,8 @@ class Piwik_API_Proxy /** * Returns true if the method is found in the API of the given class name. * - * @param string The class name - * @param string The method name + * @param string $className The class name + * @param string $methodName The method name * @return bool */ private function isMethodAvailable( $className, $methodName) @@ -378,8 +393,8 @@ class Piwik_API_Proxy /** * Checks that the class is a Singleton (presence of the getInstance() method) * - * @param string The class name - * @throws exception If the class is not a Singleton + * @param string $className The class name + * @throws Exception If the class is not a Singleton */ private function checkClassIsSingleton($className) { diff --git a/core/Access.php b/core/Access.php index d1c4a0427b..acf6980181 100644 --- a/core/Access.php +++ b/core/Access.php @@ -93,6 +93,9 @@ class Piwik_Access return self::$availableAccess; } + /** + * Constructor + */ function __construct() { $this->idsitesByAccess = array( @@ -110,7 +113,7 @@ class Piwik_Access * If the login/password is correct the user is either the SuperUser or a normal user. * We load the access levels for this user for all the websites. * - * @param null|Piwik_Auth $auth Auth adapter + * @param null|Piwik_Auth $auth Auth adapter * @return bool true on success, false if reloading access failed (when auth object wasn't specified and user is not enforced to be Super User) */ public function reloadAccess(Piwik_Auth $auth = null) @@ -166,8 +169,8 @@ class Piwik_Access /** * Returns the SQL query joining sites and access table for a given login * - * @param string $select Columns or expression to SELECT FROM table, eg. "MIN(ts_created)" - * @return string SQL query + * @param string $select Columns or expression to SELECT FROM table, eg. "MIN(ts_created)" + * @return string SQL query */ static public function getSqlAccessSite($select) { @@ -192,7 +195,8 @@ class Piwik_Access /** * We bypass the normal auth method and give the current user Super User rights. * This should be very carefully used. - * @param bool $bool + * + * @param bool $bool */ public function setSuperUser($bool = true) { @@ -241,8 +245,8 @@ class Piwik_Access * Returns an array of ID sites for which the user has at least a VIEW access. * Which means VIEW or ADMIN or SUPERUSER. * - * @return array Example if the user is ADMIN for 4 - * and has VIEW access for 1 and 7, it returns array(1, 4, 7); + * @return array Example if the user is ADMIN for 4 + * and has VIEW access for 1 and 7, it returns array(1, 4, 7); */ public function getSitesIdWithAtLeastViewAccess() { @@ -256,8 +260,8 @@ class Piwik_Access /** * Returns an array of ID sites for which the user has an ADMIN access. * - * @return array Example if the user is ADMIN for 4 and 8 - * and has VIEW access for 1 and 7, it returns array(4, 8); + * @return array Example if the user is ADMIN for 4 and 8 + * and has VIEW access for 1 and 7, it returns array(4, 8); */ public function getSitesIdWithAdminAccess() { @@ -271,8 +275,8 @@ class Piwik_Access /** * Returns an array of ID sites for which the user has a VIEW access only. * - * @return array Example if the user is ADMIN for 4 - * and has VIEW access for 1 and 7, it returns array(1, 7); + * @return array Example if the user is ADMIN for 4 + * and has VIEW access for 1 and 7, it returns array(1, 7); * @see getSitesIdWithAtLeastViewAccess() */ public function getSitesIdWithViewAccess() @@ -333,7 +337,7 @@ class Piwik_Access * This method checks that the user has ADMIN access for the given list of websites. * If the user doesn't have ADMIN access for at least one website of the list, we throw an exception. * - * @param int|array List of ID sites to check + * @param int|array $idSites List of ID sites to check * @throws Piwik_Access_NoAccessException If for any of the websites the user doesn't have an ADMIN access */ public function checkUserHasAdminAccess( $idSites ) @@ -357,8 +361,8 @@ class Piwik_Access * This method checks that the user has VIEW or ADMIN access for the given list of websites. * If the user doesn't have VIEW or ADMIN access for at least one website of the list, we throw an exception. * - * @param int|array|string List of ID sites to check (integer, array of integers, string comma separated list of integers) - * @throws Piwik_Access_NoAccessException If for any of the websites the user doesn't have an VIEW or ADMIN access + * @param int|array|string $idSites List of ID sites to check (integer, array of integers, string comma separated list of integers) + * @throws Piwik_Access_NoAccessException If for any of the websites the user doesn't have an VIEW or ADMIN access */ public function checkUserHasViewAccess( $idSites ) { @@ -378,7 +382,7 @@ class Piwik_Access } /** - * @param string $idSites + * @param int|array|string $idSites * @return array * @throws Piwik_Access_NoAccessException */ diff --git a/core/Auth.php b/core/Auth.php index c55b52176b..bef1b67d80 100644 --- a/core/Auth.php +++ b/core/Auth.php @@ -54,10 +54,10 @@ class Piwik_Auth_Result extends Zend_Auth_Result /** * Constructor for Piwik_Auth_Result * - * @param int $code - * @param string $login identity - * @param string $token_auth - * @param array $messages + * @param int $code + * @param string $login identity + * @param string $token_auth + * @param array $messages */ public function __construct($code, $login, $token_auth, array $messages = array()) { diff --git a/core/CacheFile.php b/core/CacheFile.php index 99ebe5b181..850bf20466 100644 --- a/core/CacheFile.php +++ b/core/CacheFile.php @@ -22,9 +22,18 @@ */ class Piwik_CacheFile { + /** + * @var string + */ protected $cachePath; + /** + * @var + */ protected $cachePrefix; + /** + * @param string $directory directory to use + */ function __construct($directory) { $this->cachePath = PIWIK_USER_PATH . '/tmp/cache/' . $directory . '/'; @@ -33,8 +42,8 @@ class Piwik_CacheFile /** * Function to fetch a cache entry * - * @param string $id The cache entry ID - * @return mixed False on error, or array the cache content + * @param string $id The cache entry ID + * @return array|bool False on error, or array the cache content */ function get($id) { @@ -54,9 +63,9 @@ class Piwik_CacheFile /** * A function to store content a cache entry. * - * @param string $id The cache entry ID - * @param array $content The cache content - * @return bool True if the entry was succesfully stored + * @param string $id The cache entry ID + * @param array $content The cache content + * @return bool True if the entry was succesfully stored */ function set($id, $content) { @@ -100,8 +109,8 @@ class Piwik_CacheFile /** * A function to delete a single cache entry * - * @param string $id The cache entry ID - * @return bool True if the entres were succesfully deleted + * @param string $id The cache entry ID + * @return bool True if the entres were succesfully deleted */ function delete($id) { diff --git a/core/Controller.php b/core/Controller.php index b7a3f497e3..8cb61b30a2 100644 --- a/core/Controller.php +++ b/core/Controller.php @@ -37,6 +37,10 @@ abstract class Piwik_Controller * @var Piwik_Date|null */ protected $date; + + /** + * @var int + */ protected $idSite; /** @@ -71,8 +75,9 @@ abstract class Piwik_Controller /** * Helper method to convert "today" or "yesterday" to the default timezone specified. * If the date is absolute, ie. YYYY-MM-DD, it will not be converted to the timezone - * @param string $date today, yesterday, YYYY-MM-DD - * @param string $defaultTimezone + * + * @param string $date today, yesterday, YYYY-MM-DD + * @param string $defaultTimezone default timezone to use * @return Piwik_Date */ protected function getDateParameterInTimezone($date, $defaultTimezone ) @@ -101,7 +106,8 @@ abstract class Piwik_Controller /** * Sets the date to be used by all other methods in the controller. * If the date has to be modified, it should be called just after the controller construct - * @param Piwik_Date $date + * + * @param Piwik_Date $date * @return void */ protected function setDate(Piwik_Date $date) @@ -127,8 +133,8 @@ abstract class Piwik_Controller * - echo the output of the rendering if fetch = false * - returns the output of the rendering if fetch = true * - * @param Piwik_ViewDataTable $view - * @param bool $fetch + * @param Piwik_ViewDataTable $view view object to use + * @param bool $fetch indicates whether to output or return the content * @return string|void */ protected function renderView( Piwik_ViewDataTable $view, $fetch = false) @@ -156,9 +162,9 @@ abstract class Piwik_Controller * Returns a ViewDataTable object of an Evolution graph * for the last30 days/weeks/etc. of the current period, relative to the current date. * - * @param string $currentModuleName - * @param string $currentControllerAction - * @param string $apiMethod + * @param string $currentModuleName + * @param string $currentControllerAction + * @param string $apiMethod * @return Piwik_ViewDataTable_GenerateGraphHTML_ChartEvolution */ protected function getLastUnitGraph($currentModuleName, $currentControllerAction, $apiMethod) @@ -184,13 +190,13 @@ abstract class Piwik_Controller * of different *.get reports. The returned ViewDataTable is configured with column * translations and selectable metrics. * - * @param string $currentModuleName - * @param string $currentControllerAction - * @param array $columnsToDisplay - * @param array $selectableColumns - * @param bool|string $reportDocumentation - * @param string $apiMethod The method to request the report from - * (by default, this is API.get but it can be changed for custom stuff) + * @param string $currentModuleName + * @param string $currentControllerAction + * @param array $columnsToDisplay + * @param array $selectableColumns + * @param bool|string $reportDocumentation + * @param string $apiMethod The method to request the report from + * (by default, this is API.get but it can be changed for custom stuff) * @return Piwik_ViewDataTable_GenerateGraphHTML_ChartEvolution */ protected function getLastUnitGraphAcrossPlugins($currentModuleName, $currentControllerAction, @@ -263,7 +269,7 @@ abstract class Piwik_Controller * - date: YYYY-MM-DD, today, yesterday * - period: day, week, month, year * - * @param array $paramsToSet array( 'date' => 'last50', 'viewDataTable' =>'sparkline' ) + * @param array $paramsToSet array( 'date' => 'last50', 'viewDataTable' =>'sparkline' ) * @throws Piwik_Access_NoAccessException * @return array */ @@ -313,10 +319,10 @@ abstract class Piwik_Controller * Given for example, $period = month, $lastN = 'last6', $endDate = '2011-07-01', * It will return the $date = '2011-01-01,2011-07-01' which is useful to draw graphs for the last N periods * - * @param string $period - * @param string $lastN - * @param string $endDate - * @param Piwik_Site $site + * @param string $period + * @param string $lastN + * @param string $endDate + * @param Piwik_Site $site * @return string */ static public function getDateRangeRelativeToEndDate($period, $lastN, $endDate, $site ) @@ -331,7 +337,7 @@ abstract class Piwik_Controller * Returns a numeric value from the API. * Works only for API methods that originally returns numeric values (there is no cast here) * - * @param string $methodToCall Name of method to call, eg. Referers.getNumberOfDistinctSearchEngines + * @param string $methodToCall Name of method to call, eg. Referers.getNumberOfDistinctSearchEngines * @return int|float */ protected function getNumericValue( $methodToCall ) @@ -347,8 +353,8 @@ abstract class Piwik_Controller * It will automatically build a sparkline by setting the viewDataTable=sparkline parameter in the URL. * It will also computes automatically the 'date' for the 'last30' days/weeks/etc. * - * @param string $action Method name of the controller to call in the img src - * @param array Array of name => value of parameters to set in the generated GET url + * @param string $action Method name of the controller to call in the img src + * @param array $customParameters Array of name => value of parameters to set in the generated GET url * @return string The generated URL */ protected function getUrlSparkline( $action, $customParameters = array() ) @@ -373,8 +379,9 @@ abstract class Piwik_Controller /** * Sets the first date available in the calendar - * @param Piwik_Date $minDate - * @param Piwik_View $view + * + * @param Piwik_Date $minDate + * @param Piwik_View $view * @return void */ protected function setMinDateView(Piwik_Date $minDate, $view) @@ -386,8 +393,9 @@ abstract class Piwik_Controller /** * Sets "today" in the calendar. Today does not always mean "UTC" today, eg. for websites in UTC+12. - * @param Piwik_Date $maxDate - * @param Piwik_View $view + * + * @param Piwik_Date $maxDate + * @param Piwik_View $view * @return void */ protected function setMaxDateView(Piwik_Date $maxDate, $view) @@ -396,11 +404,14 @@ abstract class Piwik_Controller $view->maxDateMonth = $maxDate->toString('m'); $view->maxDateDay = $maxDate->toString('d'); } - + /** - * Sets general variables to the view that are used by various templates and Javascript. + * Sets general variables to the view that are used by + * various templates and Javascript. * If any error happens, displays the login screen - * @param Piwik_View $view + * + * @param Piwik_View $view + * @throws Exception * @return void */ protected function setGeneralVariablesView($view) @@ -469,7 +480,7 @@ abstract class Piwik_Controller /** * Set the minimal variables in the view object * - * @param Piwik_View $view + * @param Piwik_View $view */ protected function setBasicVariablesView($view) { @@ -487,10 +498,12 @@ abstract class Piwik_Controller $view->setXFrameOptions('sameorigin'); } } - + /** - * Sets general period variables (available periods, current period, period labels) used by templates - * @param Piwik_View $view + * Sets general period variables (available periods, current period, period labels) used by templates + * + * @param Piwik_View $view + * @throws Exception * @return void */ public static function setPeriodVariablesView($view) @@ -529,12 +542,13 @@ abstract class Piwik_Controller /** * Set metrics variables (displayed metrics, available metrics) used by template * Handles the server-side of the metrics picker - * @param Piwik_View|Piwik_ViewDataTable $view - * @param string $defaultMetricDay name of the default metric for period=day - * @param string $defaultMetric name of the default metric for other periods - * @param array $metricsForDay metrics that are only available for period=day - * @param array $metricsForAllPeriods metrics that are available for all periods - * @param bool $labelDisplayed add 'label' to columns to display? + * + * @param Piwik_View|Piwik_ViewDataTable $view + * @param string $defaultMetricDay name of the default metric for period=day + * @param string $defaultMetric name of the default metric for other periods + * @param array $metricsForDay metrics that are only available for period=day + * @param array $metricsForAllPeriods metrics that are available for all periods + * @param bool $labelDisplayed add 'label' to columns to display? * @return void */ protected function setMetricsVariablesView(Piwik_ViewDataTable $view, $defaultMetricDay='nb_uniq_visitors', @@ -589,12 +603,12 @@ abstract class Piwik_Controller * Helper method used to redirect the current http request to another module/action * If specified, will also redirect to a given website, period and /or date * - * @param string $moduleToRedirect Module, eg. "MultiSites" - * @param string $actionToRedirect Action, eg. "index" - * @param string $websiteId Website ID, eg. 1 - * @param string $defaultPeriod Default period, eg. "day" - * @param string $defaultDate Default date, eg. "today" - * @param array $parameters + * @param string $moduleToRedirect Module, eg. "MultiSites" + * @param string $actionToRedirect Action, eg. "index" + * @param string $websiteId Website ID, eg. 1 + * @param string $defaultPeriod Default period, eg. "day" + * @param string $defaultDate Default date, eg. "today" + * @param array $parameters Parameters to append to url */ function redirectToIndex($moduleToRedirect, $actionToRedirect, $websiteId = null, $defaultPeriod = null, $defaultDate = null, $parameters = array()) { @@ -648,7 +662,8 @@ abstract class Piwik_Controller /** - * Returns default website that Piwik should load + * Returns default website that Piwik should load + * * @return Piwik_Site */ protected function getDefaultWebsiteId() @@ -679,7 +694,8 @@ abstract class Piwik_Controller /** * Returns default date for Piwik reports - * @return string today, 2010-01-01, etc. + * + * @return string today, 2010-01-01, etc. */ protected function getDefaultDate() { @@ -704,7 +720,8 @@ abstract class Piwik_Controller /** * Returns default date for Piwik reports - * @return string today, 2010-01-01, etc. + * + * @return string today, 2010-01-01, etc. */ protected function getDefaultPeriod() { @@ -731,8 +748,9 @@ abstract class Piwik_Controller * actions that are either invoked via AJAX or redirect to a page * within the site. The token should never appear in the browser's * address bar. - * - * @return throws exception if token doesn't match + * + * @throws Piwik_Access_NoAccessException if token doesn't match + * @return void */ protected function checkTokenInUrl() { diff --git a/core/Controller/Admin.php b/core/Controller/Admin.php index 8a66fe0fa8..cc82770598 100644 --- a/core/Controller/Admin.php +++ b/core/Controller/Admin.php @@ -18,9 +18,10 @@ abstract class Piwik_Controller_Admin extends Piwik_Controller { /** - * Used by Admin screens + * Set the minimal variables in the view object + * Extended by some admin view specific variables * - * @param Piwik_View $view + * @param Piwik_View $view */ protected function setBasicVariablesView($view) { diff --git a/core/Cookie.php b/core/Cookie.php index 7dbc0529f8..2a4c7aeb2a 100644 --- a/core/Cookie.php +++ b/core/Cookie.php @@ -27,37 +27,44 @@ class Piwik_Cookie /** * The name of the cookie + * @var string */ protected $name = null; /** * The expire time for the cookie (expressed in UNIX Timestamp) + * @var int */ protected $expire = null; /** * Restrict cookie path + * @var string */ protected $path = ''; /** * Restrict cookie to a domain (or subdomains) + * @var string */ protected $domain = ''; /** * If true, cookie should only be transmitted over secure HTTPS + * @var bool */ protected $secure = false; /** * If true, cookie will only be made available via the HTTP protocol. * Note: not well supported by browsers. + * @var bool */ protected $httponly = false; /** * The content of the cookie + * @var array */ protected $value = array(); @@ -70,10 +77,11 @@ class Piwik_Cookie * Instantiate a new Cookie object and tries to load the cookie content if the cookie * exists already. * - * @param string $cookieName cookie Name - * @param int $expire The timestamp after which the cookie will expire, eg time() + 86400; use 0 (int zero) to expire cookie at end of browser session - * @param string $path The path on the server in which the cookie will be available on. - * @param bool|string $keyStore Will be used to store several bits of data (eg. one array per website) + * @param string $cookieName cookie Name + * @param int $expire The timestamp after which the cookie will expire, eg time() + 86400; + * use 0 (int zero) to expire cookie at end of browser session + * @param string $path The path on the server in which the cookie will be available on. + * @param bool|string $keyStore Will be used to store several bits of data (eg. one array per website) */ public function __construct( $cookieName, $expire = null, $path = null, $keyStore = false) { @@ -107,7 +115,7 @@ class Piwik_Cookie /** * Returns the default expiry time, 2 years * - * @return int Timestamp in 2 years + * @return int Timestamp in 2 years */ protected function getDefaultExpire() { @@ -120,13 +128,13 @@ class Piwik_Cookie * * @link http://php.net/setcookie * - * @param string $Name Name of cookie - * @param string $Value Value of cookie - * @param int $Expires Time the cookie expires - * @param string $Path - * @param string $Domain - * @param bool $Secure - * @param bool $HTTPOnly + * @param string $Name Name of cookie + * @param string $Value Value of cookie + * @param int $Expires Time the cookie expires + * @param string $Path + * @param string $Domain + * @param bool $Secure + * @param bool $HTTPOnly */ protected function setCookie($Name, $Value, $Expires, $Path = '', $Domain = '', $Secure = false, $HTTPOnly = false) { @@ -196,8 +204,8 @@ class Piwik_Cookie /** * Extract signed content from string: content VALUE_SEPARATOR '_=' signature * - * @param string $content - * @return string|false Content or false if unsigned + * @param string $content + * @return string|bool Content or false if unsigned */ private function extractSignedContent($content) { @@ -256,7 +264,7 @@ class Piwik_Cookie * Returns the string to save in the cookie from the $this->value array of values. * It goes through the array and generates the cookie content string. * - * @return string Cookie content + * @return string Cookie content */ protected function generateContentString() { @@ -286,7 +294,7 @@ class Piwik_Cookie /** * Set cookie domain * - * @param string $domain + * @param string $domain */ public function setDomain($domain) { @@ -296,7 +304,7 @@ class Piwik_Cookie /** * Set secure flag * - * @param bool $secure + * @param bool $secure */ public function setSecure($secure) { @@ -306,7 +314,7 @@ class Piwik_Cookie /** * Set HTTP only * - * @param bool $httponly + * @param bool $httponly */ public function setHttpOnly($httponly) { @@ -323,8 +331,8 @@ class Piwik_Cookie * You should save arrays only when you are sure about their maximum data size. * A cookie has to stay small and its size shouldn't increase over time! * - * @param string Name of the value to save; the name will be used to retrieve this value - * @param string|array|numeric Value to save. If null, entry will be deleted from cookie. + * @param string $name Name of the value to save; the name will be used to retrieve this value + * @param string|array|number $value Value to save. If null, entry will be deleted from cookie. */ public function set( $name, $value ) { @@ -353,8 +361,8 @@ class Piwik_Cookie /** * Returns the value defined by $name from the cookie. * - * @param string|integer Index name of the value to return - * @return mixed The value if found, false if the value is not found + * @param string|integer Index name of the value to return + * @return mixed The value if found, false if the value is not found */ public function get( $name ) { @@ -373,7 +381,7 @@ class Piwik_Cookie /** * Returns an easy to read cookie dump * - * @return string The cookie dump + * @return string The cookie dump */ public function __toString() { @@ -386,8 +394,8 @@ class Piwik_Cookie * Escape values from the cookie before sending them back to the client * (when using the get() method). * - * @param string $value Value to be escaped - * @return mixed The value once cleaned. + * @param string $value Value to be escaped + * @return mixed The value once cleaned. */ static protected function escapeValue( $value ) { diff --git a/core/DataTable.php b/core/DataTable.php index 3f4312ec4e..114b67aa76 100644 --- a/core/DataTable.php +++ b/core/DataTable.php @@ -148,7 +148,7 @@ class Piwik_DataTable /** * Array of Piwik_DataTable_Row * - * @var array + * @var Piwik_DataTable_Row[] */ protected $rows = array(); @@ -225,8 +225,13 @@ class Piwik_DataTable * @var bool */ protected $enableRecursiveFilters = false; + + /** + * @var array + */ + protected $rowsIndexByLabel = array(); - /* + /** * @var Piwik_DataTable_Row */ protected $summaryRow = null; @@ -267,8 +272,8 @@ class Piwik_DataTable /** * Sort the dataTable rows using the php callback function * - * @param string $functionCallback - * @param string $columnSortedBy The column name. Used to then ask the datatable what column are you sorted by + * @param string $functionCallback + * @param string $columnSortedBy The column name. Used to then ask the datatable what column are you sorted by */ public function sort( $functionCallback, $columnSortedBy ) { @@ -290,6 +295,11 @@ class Piwik_DataTable } } + /** + * Returns the name of the column the tables is sorted by + * + * @return bool|string + */ public function getSortedByColumnName() { return $this->tableSortedBy; @@ -303,7 +313,11 @@ class Piwik_DataTable { $this->enableRecursiveSort = true; } - + + /** + * Enables the recursive filter. Means that when using $table->filter() + * it will also filter all subtables using the same callback + */ public function enableRecursiveFilters() { $this->enableRecursiveFilters = true; @@ -335,8 +349,8 @@ class Piwik_DataTable /** * Apply a filter to this datatable * - * @param string $className Class name, eg. "Sort" or "Piwik_DataTable_Filter_Sort" - * @param array $parameters Array of parameters to the filter, eg. array('nb_visits', 'asc') + * @param string $className Class name, eg. "Sort" or "Piwik_DataTable_Filter_Sort" + * @param array $parameters Array of parameters to the filter, eg. array('nb_visits', 'asc') */ public function filter( $className, $parameters = array() ) { @@ -349,8 +363,8 @@ class Piwik_DataTable // the first parameter of a filter is the DataTable // we add the current datatable as the parameter $parameters = array_merge(array($this), $parameters); - - $filter = $reflectionObj->newInstanceArgs($parameters); + + $filter = $reflectionObj->newInstanceArgs($parameters); $filter->enableRecursive( $this->enableRecursiveFilters ); @@ -361,8 +375,8 @@ class Piwik_DataTable * Queue a DataTable_Filter that will be applied when applyQueuedFilters() is called. * (just before sending the datatable back to the browser (or API, etc.) * - * @param string $className The class name of the filter, eg. Piwik_DataTable_Filter_Limit - * @param array $parameters The parameters to give to the filter, eg. array( $offset, $limit) for the filter Piwik_DataTable_Filter_Limit + * @param string $className The class name of the filter, eg. Piwik_DataTable_Filter_Limit + * @param array $parameters The parameters to give to the filter, eg. array( $offset, $limit) for the filter Piwik_DataTable_Filter_Limit */ public function queueFilter( $className, $parameters = array() ) { @@ -395,8 +409,9 @@ class Piwik_DataTable * * A common row to 2 DataTable is defined by the same label * - * @example tests/core/DataTable.test.php - * @param Piwik_DataTable $tableToSum + * @example tests/core/DataTable.test.php + * + * @param Piwik_DataTable $tableToSum */ public function addDataTable( Piwik_DataTable $tableToSum ) { @@ -434,8 +449,8 @@ class Piwik_DataTable /** * Returns the Piwik_DataTable_Row that has a column 'label' with the value $label * - * @param string $label Value of the column 'label' of the row to return - * @return Piwik_DataTable_Row |false The row if found, false otherwise + * @param string $label Value of the column 'label' of the row to return + * @return Piwik_DataTable_Row|false The row if found, false otherwise */ public function getRowFromLabel( $label ) { @@ -446,7 +461,13 @@ class Piwik_DataTable } return $rowId; } - + + /** + * Returns the row id for the givel label + * + * @param string $label Value of the column 'label' of the row to return + * @return bool|null + */ public function getRowIdFromLabel($label) { $this->rebuildIndexContinuously = true; @@ -473,7 +494,7 @@ class Piwik_DataTable * Returns a Piwik_DataTable that has only the one column that matches $label. * If no matches are found, an empty data table is returned. * - * @param string $label Value of the column 'label' to search for + * @param string $label Value of the column 'label' to search for * @return Piwik_DataTable */ public function getFilteredTableFromLabel($label) @@ -518,7 +539,7 @@ class Piwik_DataTable /** * Returns the ith row in the array * - * @param int $id + * @param int $id * @return Piwik_DataTable_Row or false if not found */ public function getRowFromId($id) @@ -538,8 +559,8 @@ class Piwik_DataTable /** * Returns a row that has the subtable ID matching the parameter * - * @param int $idSubTable - * @return Piwik_DataTable_Row or false if not found + * @param int $idSubTable + * @return Piwik_DataTable_Row|false if not found */ public function getRowFromIdSubDataTable($idSubTable) { @@ -557,7 +578,7 @@ class Piwik_DataTable /** * Add a row to the table and rebuild the index if necessary * - * @param Piwik_DataTable_Row $row to add at the end of the array + * @param Piwik_DataTable_Row $row to add at the end of the array */ public function addRow( Piwik_DataTable_Row $row ) { @@ -577,7 +598,7 @@ class Piwik_DataTable /** * Sets the summary row (a dataTable can have only one summary row) * - * @param Piwik_DataTable_Row $row + * @param Piwik_DataTable_Row $row */ public function addSummaryRow( Piwik_DataTable_Row $row ) { @@ -597,7 +618,7 @@ class Piwik_DataTable /** * Adds a new row from a PHP array data structure * - * @param array $row, eg. array(Piwik_DataTable_Row::COLUMNS => array( 'visits' => 13, 'test' => 'toto'),) + * @param array $row eg. array(Piwik_DataTable_Row::COLUMNS => array( 'visits' => 13, 'test' => 'toto'),) */ public function addRowFromArray( $row ) { @@ -607,7 +628,7 @@ class Piwik_DataTable /** * Adds a new row a PHP array data structure * - * @param array $row, eg. array('name' => 'google analytics', 'license' => 'commercial') + * @param array $row eg. array('name' => 'google analytics', 'license' => 'commercial') */ public function addRowFromSimpleArray( $row ) { @@ -634,7 +655,7 @@ class Piwik_DataTable /** * Returns the array containing all rows values for the requested column * - * @param $name + * @param string $name * @return array */ public function getColumn( $name ) @@ -650,7 +671,7 @@ class Piwik_DataTable /** * Returns an array containing the rows Metadata values * - * @param string $name Metadata column to return + * @param string $name Metadata column to return * @return array */ public function getRowsMetadata( $name ) @@ -745,7 +766,7 @@ class Piwik_DataTable /** * Delete a given column $name in all the rows * - * @param string $name + * @param string $name */ public function deleteColumn( $name ) { @@ -755,8 +776,8 @@ class Piwik_DataTable /** * Rename a column in all rows * - * @param string $oldName Old column name - * @param string $newName New column name + * @param string $oldName Old column name + * @param string $newName New column name */ public function renameColumn( $oldName, $newName ) { @@ -777,8 +798,8 @@ class Piwik_DataTable /** * Delete columns by name in all rows * - * @param array $names - * @param bool $deleteRecursiveInSubtables + * @param array $names + * @param bool $deleteRecursiveInSubtables */ public function deleteColumns($names, $deleteRecursiveInSubtables = false) { @@ -805,7 +826,7 @@ class Piwik_DataTable /** * Deletes the ith row * - * @param int $id + * @param int $id * @throws Exception if the row $id cannot be found * @return */ @@ -827,8 +848,8 @@ class Piwik_DataTable * Deletes all row from offset, offset + limit. * If limit is null then limit = $table->getRowsCount() * - * @param int $offset - * @param int $limit + * @param int $offset + * @param int $limit * @return int */ public function deleteRowsOffset( $offset, $limit = null ) @@ -866,7 +887,7 @@ class Piwik_DataTable /** * Deletes the rows from the list of rows ID * - * @param array $aKeys ID of the rows to delete + * @param array $aKeys ID of the rows to delete * @throws Exception if any of the row to delete couldn't be found */ public function deleteRows( array $aKeys ) @@ -894,8 +915,8 @@ class Piwik_DataTable * Returns true if both DataTable are exactly the same. * Used in unit tests. * - * @param Piwik_DataTable $table1 - * @param Piwik_DataTable $table2 + * @param Piwik_DataTable $table1 + * @param Piwik_DataTable $table2 * @return bool */ static public function isEqual(Piwik_DataTable $table1, Piwik_DataTable $table2) @@ -940,11 +961,10 @@ class Piwik_DataTable * won't work. * * @throws Exception if an infinite recursion is found (a table row's has a subtable that is one of its parent table) - * @param int If not null, defines the number of rows maximum of the serialized dataTable - * If $addSummaryRowAfterNRows is less than the size of the table, a SummaryRow will be added at the end of the table, that - * is the sum of the values of all the rows after the Nth row. All the rows after the Nth row will be deleted. - * - * @return array Serialized arrays + * @param int $maximumRowsInDataTable If not null, defines the number of rows maximum of the serialized dataTable + * @param int $maximumRowsInSubDataTable If not null, defines the number of rows maximum of the serialized subDataTable + * @param string $columnToSortByBeforeTruncation Column to sort by before truncation + * @return array Serialized arrays * array( // Datatable level0 * 0 => 'eghuighahgaueytae78yaet7yaetae', * @@ -1019,7 +1039,7 @@ class Piwik_DataTable * * The function creates all the necessary DataTable_Row * - * @param string string of serialized datatable + * @param string $stringSerialized string of serialized datatable * @throws Exception */ public function addRowsFromSerializedArray( $stringSerialized ) @@ -1035,19 +1055,16 @@ class Piwik_DataTable /** * Loads the DataTable from a PHP array data structure * - * @param array Array with the following structure - * array( - * // row1 - * array( - * Piwik_DataTable_Row::COLUMNS => array( col1_name => value1, col2_name => value2, ...), - * Piwik_DataTable_Row::METADATA => array( metadata1_name => value1, ...), // see Piwik_DataTable_Row - * - * ), - * - * // row2 - * array( ... ), - * - * ) + * @param array $array Array with the following structure + * array( + * // row1 + * array( + * Piwik_DataTable_Row::COLUMNS => array( col1_name => value1, col2_name => value2, ...), + * Piwik_DataTable_Row::METADATA => array( metadata1_name => value1, ...), // see Piwik_DataTable_Row + * ), + * // row2 + * array( ... ), + * ) */ public function addRowsFromArray( $array ) { @@ -1079,11 +1096,11 @@ class Piwik_DataTable * Basically maps a simple multidimensional php array to a DataTable. * Not recursive (if a row contains a php array itself, it won't be loaded) * - * @param array Array with the simple structure: - * array( - * array( col1_name => valueA, col2_name => valueC, ...), - * array( col1_name => valueB, col2_name => valueD, ...), - * ) + * @param array $array Array with the simple structure: + * array( + * array( col1_name => valueA, col2_name => valueC, ...), + * array( col1_name => valueB, col2_name => valueD, ...), + * ) * @throws Exception * @return */ @@ -1211,8 +1228,8 @@ class Piwik_DataTable * ), * ) * - * @param array $array See method description - * @param array|null $subtablePerLabel see method description + * @param array $array See method description + * @param array|null $subtablePerLabel See method description */ public function addRowsFromArrayWithIndexLabel( $array, $subtablePerLabel = null) { @@ -1240,7 +1257,8 @@ class Piwik_DataTable /** * Set the array of parent ids - * @param array $parents + * + * @param array $parents */ public function setParents($parents) { @@ -1249,7 +1267,8 @@ class Piwik_DataTable /** * Get parents - * @return array of all parents, root level first + * + * @return array of all parents, root level first */ public function getParents() { if ($this->parents == null) @@ -1274,7 +1293,7 @@ class Piwik_DataTable * Sets the maximum nesting level to at least a certain value. If the current value is * greater than the supplied level, the maximum nesting level is not changed. * - * @param int $atLeastLevel + * @param int $atLeastLevel */ static public function setMaximumDepthLevelAllowedAtLeast( $atLeastLevel ) { diff --git a/core/DataTable/Filter.php b/core/DataTable/Filter.php index 95beee04ea..56c8fd7be2 100644 --- a/core/DataTable/Filter.php +++ b/core/DataTable/Filter.php @@ -26,6 +26,15 @@ */ abstract class Piwik_DataTable_Filter { + /** + * @var bool + */ + protected $enableRecursive = false; + + /** + * @throws Exception + * @param Piwik_DataTable $table + */ public function __construct($table) { if(!($table instanceof Piwik_DataTable)) @@ -33,16 +42,31 @@ abstract class Piwik_DataTable_Filter throw new Exception("The filter accepts only a Piwik_DataTable object."); } } - + + /** + * Filters the given data table + * + * @param Piwik_DataTable $table + * @return mixed + */ abstract public function filter($table); - - protected $enableRecursive = false; - + + /** + * Enables/Disables the recursive mode + * + * @param $bool + */ public function enableRecursive($bool) { $this->enableRecursive = (bool)$bool; } - + + /** + * Filters a subtable + * + * @param Piwik_DataTable_Row $row + * @return mixed + */ public function filterSubTable(Piwik_DataTable_Row $row) { if(!$this->enableRecursive) diff --git a/core/Date.php b/core/Date.php index b30d03dce2..3da0b5bdf1 100644 --- a/core/Date.php +++ b/core/Date.php @@ -18,10 +18,26 @@ class Piwik_Date { /** + * The stored timestamp is always UTC based. + * The returned timestamp via getTimestamp() will have the conversion applied + * @var int|null + */ + protected $timestamp = null; + + /** + * Timezone the current date object is set to. + * Timezone will only affect the returned timestamp via getTimestamp() + * @var string + */ + protected $timezone = 'UTC'; + + const DATE_TIME_FORMAT = 'Y-m-d H:i:s'; + + /** * Builds a Piwik_Date object * - * @param int $timestamp - * @param string $timezone + * @param int $timestamp + * @param string $timezone * @throws Exception */ protected function __construct( $timestamp, $timezone = 'UTC') @@ -34,14 +50,13 @@ class Piwik_Date $this->timestamp = $timestamp ; } - /** * Returns a Piwik_Date objects. * - * @param string $dateString 'today' 'yesterday' or any YYYY-MM-DD or timestamp - * @param string $timezone if specified, the dateString will be relative to this $timezone. - * For example, today in UTC+12 will be a timestamp in the future for UTC. - * This is different from using ->setTimezone() + * @param string|self $dateString 'today' 'yesterday' or any YYYY-MM-DD or timestamp + * @param string $timezone if specified, the dateString will be relative to this $timezone. + * For example, today in UTC+12 will be a timestamp in the future for UTC. + * This is different from using ->setTimezone() * @throws Exception * @return Piwik_Date */ @@ -99,20 +114,6 @@ class Piwik_Date return Piwik_Date::factory($timestamp); } - /* - * The stored timestamp is always UTC based. - * The returned timestamp via getTimestamp() will have the conversion applied - */ - protected $timestamp = null; - - /* - * Timezone the current date object is set to. - * Timezone will only affect the returned timestamp via getTimestamp() - */ - protected $timezone = 'UTC'; - - const DATE_TIME_FORMAT = 'Y-m-d H:i:s'; - /** * Returns the datetime of the current timestamp * @@ -152,7 +153,7 @@ class Piwik_Date * This timezone is used to offset the UTC timestamp returned by @see getTimestamp() * Doesn't modify $this * - * @param string $timezone 'UTC', 'Europe/London', ... + * @param string $timezone 'UTC', 'Europe/London', ... * @return Piwik_Date */ public function setTimezone($timezone) @@ -164,8 +165,8 @@ class Piwik_Date * Helper function that returns the offset in the timezone string 'UTC+14' * Returns false if the timezone is not UTC+X or UTC-X * - * @param string $timezone - * @return int or false + * @param string $timezone + * @return int|bool utc offset or false */ static protected function extractUtcOffset($timezone) { @@ -189,9 +190,9 @@ class Piwik_Date /** * Adjusts a UNIX timestamp in UTC to a specific timezone. * - * @param int $timestamp The UNIX timestamp to adjust. - * @param string $timezone The timezone to adjust to. - * @return int The adjusted time as seconds from EPOCH. + * @param int $timestamp The UNIX timestamp to adjust. + * @param string $timezone The timezone to adjust to. + * @return int The adjusted time as seconds from EPOCH. */ static public function adjustForTimezone($timestamp, $timezone) { @@ -255,7 +256,7 @@ class Piwik_Date /** * Returns true if the current date is older than the given $date * - * @param Piwik_Date $date + * @param Piwik_Date $date * @return bool */ public function isLater( Piwik_Date $date) @@ -266,7 +267,7 @@ class Piwik_Date /** * Returns true if the current date is earlier than the given $date * - * @param Piwik_Date $date + * @param Piwik_Date $date * @return bool */ public function isEarlier(Piwik_Date $date) @@ -278,7 +279,7 @@ class Piwik_Date * Returns the Y-m-d representation of the string. * You can specify the output, see the list on php.net/date * - * @param string $part + * @param string $part * @return string */ public function toString($part = 'Y-m-d') @@ -301,8 +302,8 @@ class Piwik_Date * Returns 0 if equal, -1 if current week is earlier or 1 if current week is later * Example: 09.Jan.2007 13:07:25 -> compareWeek(2); -> 0 * - * @param Piwik_Date $date - * @return integer 0 = equal, 1 = later, -1 = earlier + * @param Piwik_Date $date + * @return int 0 = equal, 1 = later, -1 = earlier */ public function compareWeek(Piwik_Date $date) { @@ -324,8 +325,8 @@ class Piwik_Date * Returns 0 if equal, -1 if current month is earlier or 1 if current month is later * For example: 10.03.2000 -> 15.03.1950 -> 0 * - * @param Piwik_Date $date Month to compare - * @return integer 0 = equal, 1 = later, -1 = earlier + * @param Piwik_Date $date Month to compare + * @return int 0 = equal, 1 = later, -1 = earlier */ function compareMonth( Piwik_Date $date ) { @@ -396,7 +397,7 @@ class Piwik_Date * Sets the time part of the date * Doesn't modify $this * - * @param string $time HH:MM:SS + * @param string $time HH:MM:SS * @return Piwik_Date The new date with the time part set */ public function setTime($time) @@ -409,7 +410,7 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param int Day eg. 31 + * @param int $day Day eg. 31 * @return Piwik_Date new date */ public function setDay( $day ) @@ -431,7 +432,7 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param int 2010 + * @param int $year 2010 * @return Piwik_Date new date */ public function setYear( $year ) @@ -453,7 +454,7 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param $n + * @param int $n * @return Piwik_Date new date */ public function subDay( $n ) @@ -471,7 +472,7 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param $n + * @param int $n * @return Piwik_Date new date */ public function subWeek( $n ) @@ -484,7 +485,7 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param $n + * @param int $n * @return Piwik_Date new date */ public function subMonth( $n ) @@ -510,7 +511,7 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param $n + * @param int $n * @return Piwik_Date new date */ public function subYear( $n ) @@ -535,8 +536,8 @@ class Piwik_Date * Returns a localized date string, given a template. * Allowed tags are: %day%, %shortDay%, %longDay%, etc. * - * @param string $template string eg. %shortMonth% %longYear% - * @return string eg. "Aug 2009" + * @param string $template string eg. %shortMonth% %longYear% + * @return string eg. "Aug 2009" */ public function getLocalized($template) { @@ -562,8 +563,8 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param int Number of days to add - * @return Piwik_Date new date + * @param int $n Number of days to add + * @return Piwik_Date new date */ public function addDay( $n ) { @@ -576,8 +577,8 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param int Number of hours to add - * @return Piwik_Date new date + * @param int $n Number of hours to add + * @return Piwik_Date new date */ public function addHour( $n ) { @@ -588,9 +589,9 @@ class Piwik_Date /** * Adds N number of hours to a UNIX timestamp and returns the result. * - * @param int $timestamp The timestamp to add to. - * @param int|float Number of hours to add. - * @return int The result as a UNIX timestamp. + * @param int $timestamp The timestamp to add to. + * @param number $n Number of hours to add. + * @return int The result as a UNIX timestamp. */ public static function addHourTo( $timestamp, $n ) { @@ -627,8 +628,8 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param int Number of hours to substract - * @return Piwik_Date new date + * @param int $n Number of hours to substract + * @return Piwik_Date new date */ public function subHour( $n ) { @@ -640,9 +641,9 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param $n - * @param $period period to add - * @return Piwik_Date new date + * @param int $n + * @param string $period period to add (WEEK, DAY,...) + * @return Piwik_Date new date */ public function addPeriod( $n, $period ) { @@ -662,9 +663,9 @@ class Piwik_Date * Returned is the new date object * Doesn't modify $this * - * @param $n - * @param $period period to sub - * @return Piwik_Date new date + * @param int $n + * @param string $period period to sub + * @return Piwik_Date new date */ public function subPeriod( $n, $period ) { diff --git a/core/Db/Adapter.php b/core/Db/Adapter.php index 88c4ba2df2..cb028ff50b 100644 --- a/core/Db/Adapter.php +++ b/core/Db/Adapter.php @@ -22,7 +22,7 @@ class Piwik_Db_Adapter * @param string $adapterName database adapter name * @param array $dbInfos database connection info * @param bool $connect - * @return mixed (Piwik_Db_Adapter_Mysqli, Piwik_Db_Adapter_Pdo_Mysql, etc) + * @return Piwik_Db_Adapter_Interface */ public static function factory($adapterName, & $dbInfos, $connect = true) { @@ -72,7 +72,7 @@ class Piwik_Db_Adapter /** * Get adapter class name * - * @param string $adapterName + * @param string $adapterName * @return string */ private static function getAdapterClassName($adapterName) @@ -83,7 +83,7 @@ class Piwik_Db_Adapter /** * Get default port for named adapter * - * @param string $adapterName + * @param string $adapterName * @return int */ public static function getDefaultPortForAdapter($adapterName) diff --git a/core/Db/Adapter/Interface.php b/core/Db/Adapter/Interface.php index 69ce7641e1..81535d5bfa 100644 --- a/core/Db/Adapter/Interface.php +++ b/core/Db/Adapter/Interface.php @@ -59,8 +59,8 @@ interface Piwik_Db_Adapter_Interface /** * Test error number * - * @param Exception $e - * @param string $errno + * @param Exception $e + * @param string $errno * @return bool */ public function isErrNo($e, $errno); diff --git a/core/Db/Adapter/Mysqli.php b/core/Db/Adapter/Mysqli.php index 0e656f194e..f666b1269b 100644 --- a/core/Db/Adapter/Mysqli.php +++ b/core/Db/Adapter/Mysqli.php @@ -16,6 +16,11 @@ */ class Piwik_Db_Adapter_Mysqli extends Zend_Db_Adapter_Mysqli implements Piwik_Db_Adapter_Interface { + /** + * Constructor + * + * @param array|Zend_Config $config database configuration + */ public function __construct($config) { // Enable LOAD DATA INFILE @@ -43,6 +48,7 @@ class Piwik_Db_Adapter_Mysqli extends Zend_Db_Adapter_Mysqli implements Piwik_Db /** * Check MySQL version + * * @throws Exception */ public function checkServerVersion() @@ -57,6 +63,7 @@ class Piwik_Db_Adapter_Mysqli extends Zend_Db_Adapter_Mysqli implements Piwik_Db /** * Check client version compatibility against database server + * * @throws Exception */ public function checkClientVersion() @@ -105,8 +112,8 @@ class Piwik_Db_Adapter_Mysqli extends Zend_Db_Adapter_Mysqli implements Piwik_Db /** * Test error number * - * @param Exception $e - * @param string $errno + * @param Exception $e + * @param string $errno * @return bool */ public function isErrNo($e, $errno) @@ -129,8 +136,8 @@ class Piwik_Db_Adapter_Mysqli extends Zend_Db_Adapter_Mysqli implements Piwik_Db * Workaround some SQL statements not compatible with prepare(). * See http://framework.zend.com/issues/browse/ZF-1398 * - * @param string $sqlQuery - * @return int Number of rows affected (SELECT/INSERT/UPDATE/DELETE) + * @param string $sqlQuery + * @return int Number of rows affected (SELECT/INSERT/UPDATE/DELETE) */ public function exec( $sqlQuery ) { diff --git a/core/Db/Adapter/Pdo/Mssql.php b/core/Db/Adapter/Pdo/Mssql.php index e8c29f6517..68b8fb68d9 100644 --- a/core/Db/Adapter/Pdo/Mssql.php +++ b/core/Db/Adapter/Pdo/Mssql.php @@ -131,6 +131,7 @@ class Piwik_Db_Pdo_Mssql extends Zend_Db_Adapter_Pdo_Mssql implements Piwik_Db_A /** * Check MSSQL version + * * @throws Exception */ public function checkServerVersion() @@ -144,6 +145,11 @@ class Piwik_Db_Pdo_Mssql extends Zend_Db_Adapter_Pdo_Mssql implements Piwik_Db_A } + /** + * Returns the Mssql server version + * + * @return null|string + */ public function getServerVersion() { try @@ -164,6 +170,7 @@ class Piwik_Db_Pdo_Mssql extends Zend_Db_Adapter_Pdo_Mssql implements Piwik_Db_A /** * Check client version compatibility against database server + * * @throws Exception */ public function checkClientVersion() @@ -216,8 +223,8 @@ class Piwik_Db_Pdo_Mssql extends Zend_Db_Adapter_Pdo_Mssql implements Piwik_Db_A /** * Test error number * - * @param Exception $e - * @param string $errno + * @param Exception $e + * @param string $errno * @return bool */ public function isErrNo($e, $errno) diff --git a/core/Db/Adapter/Pdo/Mysql.php b/core/Db/Adapter/Pdo/Mysql.php index acc8d2f079..89c6d44000 100644 --- a/core/Db/Adapter/Pdo/Mysql.php +++ b/core/Db/Adapter/Pdo/Mysql.php @@ -16,6 +16,11 @@ */ class Piwik_Db_Adapter_Pdo_Mysql extends Zend_Db_Adapter_Pdo_Mysql implements Piwik_Db_Adapter_Interface { + /** + * Constructor + * + * @param array|Zend_Config $config database configuration + */ public function __construct($config) { // Enable LOAD DATA INFILE @@ -75,20 +80,22 @@ class Piwik_Db_Adapter_Pdo_Mysql extends Zend_Db_Adapter_Pdo_Mysql implements Pi /** * Check MySQL version + * * @throws Exception */ public function checkServerVersion() { $serverVersion = $this->getServerVersion(); - $requiredVersion = Piwik_Config::getInstance()->General['minimum_mysql_version']; - if(version_compare($serverVersion, $requiredVersion) === -1) - { - throw new Exception(Piwik_TranslateException('General_ExceptionDatabaseVersion', array('MySQL', $serverVersion, $requiredVersion))); - } + $requiredVersion = Piwik_Config::getInstance()->General['minimum_mysql_version']; + if(version_compare($serverVersion, $requiredVersion) === -1) + { + throw new Exception(Piwik_TranslateException('General_ExceptionDatabaseVersion', array('MySQL', $serverVersion, $requiredVersion))); + } } /** * Check client version compatibility against database server + * * @throws Exception */ public function checkClientVersion() @@ -137,8 +144,8 @@ class Piwik_Db_Adapter_Pdo_Mysql extends Zend_Db_Adapter_Pdo_Mysql implements Pi /** * Test error number * - * @param Exception $e - * @param string $errno + * @param Exception $e + * @param string $errno * @return bool */ public function isErrNo($e, $errno) @@ -188,8 +195,8 @@ class Piwik_Db_Adapter_Pdo_Mysql extends Zend_Db_Adapter_Pdo_Mysql implements Pi * Prepares and executes an SQL statement with bound data. * Caches prepared statements to avoid preparing the same query more than once * - * @param mixed $sql - * @param mixed $bind + * @param string|Zend_Db_Select $sql The SQL statement with placeholders. + * @param array $bind An array of data to bind to the placeholders. * @return Zend_Db_Statement_Interface */ public function query($sql, $bind = array()) diff --git a/core/Db/Adapter/Pdo/Pgsql.php b/core/Db/Adapter/Pdo/Pgsql.php index 4d4e2429a8..66351507c7 100644 --- a/core/Db/Adapter/Pdo/Pgsql.php +++ b/core/Db/Adapter/Pdo/Pgsql.php @@ -36,6 +36,7 @@ class Piwik_Db_Adapter_Pdo_Pgsql extends Zend_Db_Adapter_Pdo_Pgsql implements Pi /** * Check PostgreSQL version + * * @throws Exception */ public function checkServerVersion() @@ -98,8 +99,8 @@ class Piwik_Db_Adapter_Pdo_Pgsql extends Zend_Db_Adapter_Pdo_Pgsql implements Pi /** * Test error number * - * @param Exception $e - * @param string $errno + * @param Exception $e + * @param string $errno * @return bool */ public function isErrNo($e, $errno) diff --git a/core/Db/Schema.php b/core/Db/Schema.php index 382b9adb30..5424fbed17 100644 --- a/core/Db/Schema.php +++ b/core/Db/Schema.php @@ -20,8 +20,18 @@ */ class Piwik_Db_Schema { + /** + * Singleton instance + * + * @var Piwik_Db_Schema + */ static private $instance = null; + /** + * Type of database schema + * + * @var string + */ private $schema = null; /** @@ -41,7 +51,7 @@ class Piwik_Db_Schema /** * Get schema class name * - * @param string $schemaName + * @param string $schemaName * @return string */ private static function getSchemaClassName($schemaName) @@ -52,7 +62,7 @@ class Piwik_Db_Schema /** * Get list of schemas * - * @param string $adapterName + * @param string $adapterName * @return array */ public static function getSchemas($adapterName) @@ -159,8 +169,8 @@ class Piwik_Db_Schema /** * Get the SQL to create a specific Piwik table * - * @param string $tableName - * @return string SQL + * @param string $tableName name of the table to create + * @return string SQL */ public function getTableCreateSql( $tableName ) { @@ -170,7 +180,7 @@ class Piwik_Db_Schema /** * Get the SQL to create Piwik tables * - * @return array of strings containing SQL + * @return array array of strings containing SQL */ public function getTablesCreateSql() { @@ -179,7 +189,8 @@ class Piwik_Db_Schema /** * Create database - * @param null|string $dbName + * + * @param null|string $dbName database name to create */ public function createDatabase( $dbName = null ) { @@ -220,7 +231,8 @@ class Piwik_Db_Schema /** * Drop specific tables - * @param array $doNotDelete + * + * @param array $doNotDelete */ public function dropTables( $doNotDelete = array() ) { @@ -241,8 +253,8 @@ class Piwik_Db_Schema /** * Get list of tables installed * - * @param bool $forceReload Invalidate cache - * @return array Tables installed + * @param bool $forceReload Invalidate cache + * @return array installed tables */ public function getTablesInstalled($forceReload = true) { @@ -252,36 +264,10 @@ class Piwik_Db_Schema /** * Returns true if Piwik tables exist * - * @return bool True if tables exist; false otherwise + * @return bool True if tables exist; false otherwise */ public function hasTables() { return $this->getSchema()->hasTables(); } -} - -/** - * Database schema interface - * - * @package Piwik - * @subpackage Piwik_Db - */ -interface Piwik_Db_Schema_Interface -{ - static public function isAvailable(); - - public function getTableCreateSql($tableName); - public function getTablesCreateSql(); - - public function createDatabase( $dbName = null ); - public function dropDatabase(); - - public function createTables(); - public function createAnonymousUser(); - public function truncateAllTables(); - public function dropTables( $doNotDelete = array() ); - - public function getTablesNames(); - public function getTablesInstalled($forceReload = true); - public function hasTables(); -} +}
\ No newline at end of file diff --git a/core/Db/Schema/Interface.php b/core/Db/Schema/Interface.php new file mode 100644 index 0000000000..7f437822c9 --- /dev/null +++ b/core/Db/Schema/Interface.php @@ -0,0 +1,99 @@ +<?php +/** + * Piwik - Open source web analytics + * + * @link http://piwik.org + * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later + * @version $Id$ + * + * @category Piwik + * @package Piwik + */ + +/** + * Database schema interface + * + * @package Piwik + * @subpackage Piwik_Db + */ +interface Piwik_Db_Schema_Interface +{ + /** + * Is this schema available? + * + * @return bool True if schema is available; false otherwise + */ + static public function isAvailable(); + + /** + * Get the SQL to create a specific Piwik table + * + * @param string $tableName + * @return string SQL + */ + public function getTableCreateSql($tableName); + + /** + * Get the SQL to create Piwik tables + * + * @return array array of strings containing SQL + */ + public function getTablesCreateSql(); + + /** + * Create database + * + * @param string $dbName Name of the database to create + */ + public function createDatabase( $dbName = null ); + + /** + * Drop database + */ + public function dropDatabase(); + + /** + * Create all tables + */ + public function createTables(); + + /** + * Creates an entry in the User table for the "anonymous" user. + */ + public function createAnonymousUser(); + + /** + * Truncate all tables + */ + public function truncateAllTables(); + + /** + * Drop specific tables + * + * @param array $doNotDelete Names of tables to not delete + */ + public function dropTables( $doNotDelete = array() ); + + /** + * Names of all the prefixed tables in piwik + * Doesn't use the DB + * + * @return array Table names + */ + public function getTablesNames(); + + /** + * Get list of tables installed + * + * @param bool $forceReload Invalidate cache + * @return array installed Tables + */ + public function getTablesInstalled($forceReload = true); + + /** + * Checks whether any table exists + * + * @return bool True if tables exist; false otherwise + */ + public function hasTables(); +} diff --git a/core/Db/Schema/Myisam.php b/core/Db/Schema/Myisam.php index c77547cce3..bbec50cef3 100644 --- a/core/Db/Schema/Myisam.php +++ b/core/Db/Schema/Myisam.php @@ -21,8 +21,8 @@ class Piwik_Db_Schema_Myisam implements Piwik_Db_Schema_Interface /** * Is this MySQL storage engine available? * - * @param string $engineName - * @return bool True if available and enabled; false otherwise + * @param string $engineName + * @return bool True if available and enabled; false otherwise */ static private function hasStorageEngine($engineName) { @@ -39,7 +39,7 @@ class Piwik_Db_Schema_Myisam implements Piwik_Db_Schema_Interface /** * Is this schema available? * - * @return bool True if schema is available; false otherwise + * @return bool True if schema is available; false otherwise */ static public function isAvailable() { @@ -49,7 +49,7 @@ class Piwik_Db_Schema_Myisam implements Piwik_Db_Schema_Interface /** * Get the SQL to create Piwik tables * - * @return array of strings containing SQL + * @return array array of strings containing SQL */ public function getTablesCreateSql() { @@ -385,9 +385,9 @@ class Piwik_Db_Schema_Myisam implements Piwik_Db_Schema_Interface /** * Get the SQL to create a specific Piwik table * - * @param string $tableName + * @param string $tableName * @throws Exception - * @return string SQL + * @return string SQL */ public function getTableCreateSql( $tableName ) { @@ -405,7 +405,7 @@ class Piwik_Db_Schema_Myisam implements Piwik_Db_Schema_Interface * Names of all the prefixed tables in piwik * Doesn't use the DB * - * @return array Table names + * @return array Table names */ public function getTablesNames() { @@ -425,8 +425,8 @@ class Piwik_Db_Schema_Myisam implements Piwik_Db_Schema_Interface /** * Get list of tables installed * - * @param bool $forceReload Invalidate cache - * @return array Tables installed + * @param bool $forceReload Invalidate cache + * @return array installed Tables */ public function getTablesInstalled($forceReload = true) { @@ -461,9 +461,9 @@ class Piwik_Db_Schema_Myisam implements Piwik_Db_Schema_Interface } /** - * Do tables exist? + * Checks whether any table exists * - * @return bool True if tables exist; false otherwise + * @return bool True if tables exist; false otherwise */ public function hasTables() { @@ -473,7 +473,7 @@ class Piwik_Db_Schema_Myisam implements Piwik_Db_Schema_Interface /** * Create database * - * @param string $dbName + * @param string $dbName Name of the database to create */ public function createDatabase( $dbName = null ) { diff --git a/core/ErrorHandler.php b/core/ErrorHandler.php index 6536173b06..02bac5b962 100644 --- a/core/ErrorHandler.php +++ b/core/ErrorHandler.php @@ -13,11 +13,11 @@ /** * Error handler used to display nicely errors in Piwik * - * @param int $errno Error number - * @param string $errstr Error message - * @param string $errfile File name - * @param int $errline Line number - * @return + * @param int $errno Error number + * @param string $errstr Error message + * @param string $errfile File name + * @param int $errline Line number + * @return void */ function Piwik_ErrorHandler($errno, $errstr, $errfile, $errline) { diff --git a/core/ExceptionHandler.php b/core/ExceptionHandler.php index 55b0c6bb2b..1c19fe3a79 100644 --- a/core/ExceptionHandler.php +++ b/core/ExceptionHandler.php @@ -13,7 +13,7 @@ /** * Exception handler used to display nicely exceptions in Piwik * - * @param Exception $exception + * @param Exception $exception * @throws Exception */ function Piwik_ExceptionHandler(Exception $exception) diff --git a/core/Http.php b/core/Http.php index a942d09717..b7f61a2251 100644 --- a/core/Http.php +++ b/core/Http.php @@ -47,14 +47,14 @@ class Piwik_Http * If no $destinationPath is specified, the trimmed response (without header) is returned as a string. * If a $destinationPath is specified, the response (without header) is saved to a file. * - * @param string $aUrl - * @param int $timeout - * @param string $userAgent - * @param string $destinationPath - * @param int $followDepth - * @param bool $acceptLanguage + * @param string $aUrl + * @param int $timeout + * @param string $userAgent + * @param string $destinationPath + * @param int $followDepth + * @param bool $acceptLanguage * @throws Exception - * @return bool true (or string) on success; false on HTTP response error code (1xx or 4xx) + * @return bool true (or string) on success; false on HTTP response error code (1xx or 4xx) */ static public function sendHttpRequest($aUrl, $timeout, $userAgent = null, $destinationPath = null, $followDepth = 0, $acceptLanguage = false) { @@ -77,17 +77,17 @@ class Piwik_Http /** * Sends http request using the specified transport method * - * @param string $method - * @param string $aUrl - * @param int $timeout - * @param string $userAgent - * @param string $destinationPath - * @param resource $file - * @param int $followDepth - * @param bool|string $acceptLanguage Accept-language header - * @param bool $acceptInvalidSslCertificate Only used with $method == 'curl'. If set to true (NOT recommended!) the SSL certificate will not be checked + * @param string $method + * @param string $aUrl + * @param int $timeout + * @param string $userAgent + * @param string $destinationPath + * @param resource $file + * @param int $followDepth + * @param bool|string $acceptLanguage Accept-language header + * @param bool $acceptInvalidSslCertificate Only used with $method == 'curl'. If set to true (NOT recommended!) the SSL certificate will not be checked * @throws Exception - * @return bool true (or string) on success; false on HTTP response error code (1xx or 4xx) + * @return bool true (or string) on success; false on HTTP response error code (1xx or 4xx) */ static public function sendHttpRequestBy($method = 'socket', $aUrl, $timeout, $userAgent = null, $destinationPath = null, $file = null, $followDepth = 0, $acceptLanguage = false, $acceptInvalidSslCertificate = false) { @@ -475,10 +475,11 @@ class Piwik_Http /** * Fetch the file at $url in the destination $destinationPath * - * @param string $url - * @param string $destinationPath - * @param int $tries - * @return true on success, throws Exception on failure + * @param string $url + * @param string $destinationPath + * @param int $tries + * @throws Exception + * @return bool true on success, throws Exception on failure */ static public function fetchRemoteFile($url, $destinationPath = null, $tries = 0) { diff --git a/core/IP.php b/core/IP.php index 8e52059abe..b7bdf54e71 100644 --- a/core/IP.php +++ b/core/IP.php @@ -51,7 +51,7 @@ class Piwik_IP /** * Sanitize human-readable IP address. * - * @param string $ipString IP address + * @param string $ipString IP address * @return string|false */ static public function sanitizeIp($ipString) @@ -106,8 +106,8 @@ class Piwik_IP * - IPv6 block using CIDR notation, e.g., 2001:DB8::/48 represents the IPv6 addresses from 2001:DB8:0:0:0:0:0:0 to 2001:DB8:0:FFFF:FFFF:FFFF:FFFF:FFFF * - wildcards, e.g., 192.168.0.* * - * @param string $ipRangeString IP address range - * @return string|false IP address range in CIDR notation + * @param string $ipRangeString IP address range + * @return string|false IP address range in CIDR notation */ static public function sanitizeIpRange($ipRangeString) { @@ -155,8 +155,8 @@ class Piwik_IP /** * Convert presentation format IP address to network address format * - * @param string $ipString IP address, either IPv4 or IPv6, e.g., "127.0.0.1" - * @return string Binary-safe string, e.g., "\x7F\x00\x00\x01" + * @param string $ipString IP address, either IPv4 or IPv6, e.g., "127.0.0.1" + * @return string Binary-safe string, e.g., "\x7F\x00\x00\x01" */ static public function P2N($ipString) { @@ -170,8 +170,8 @@ class Piwik_IP * * @see prettyPrint() * - * @param string $ip IP address in network address format - * @return string IP address in presentation format + * @param string $ip IP address in network address format + * @return string IP address in presentation format */ static public function N2P($ip) { @@ -183,8 +183,8 @@ class Piwik_IP /** * Alias for N2P() * - * @param string $ip IP address in network address format - * @return string IP address in presentation format + * @param string $ip IP address in network address format + * @return string IP address in presentation format */ static public function prettyPrint($ip) { @@ -194,8 +194,8 @@ class Piwik_IP /** * Is this an IPv4, IPv4-compat, or IPv4-mapped address? * - * @param string $ip IP address in network address format - * @return bool True if IPv4, else false + * @param string $ip IP address in network address format + * @return bool True if IPv4, else false */ static public function isIPv4($ip) { @@ -230,8 +230,8 @@ class Piwik_IP * This function does not support the long (or its string representation) * returned by the built-in ip2long() function, from Piwik 1.3 and earlier. * - * @param string $ip IPv4 address in network address format - * @return string IP address in presentation format + * @param string $ip IPv4 address in network address format + * @return string IP address in presentation format */ static public function long2ip($ip) { @@ -258,8 +258,8 @@ class Piwik_IP /** * Get low and high IP addresses for a specified range. * - * @param array $ipRange An IP address range in presentation format - * @return array|false Array ($lowIp, $highIp) in network address format, or false if failure + * @param array $ipRange An IP address range in presentation format + * @return array|false Array ($lowIp, $highIp) in network address format, or false if failure */ static public function getIpsForRange($ipRange) { @@ -302,9 +302,9 @@ class Piwik_IP * * An IPv4-mapped address should be range checked with an IPv4-mapped address range. * - * @param string $ip IP address in network address format - * @param array $ipRanges List of IP address ranges - * @return bool True if in any of the specified IP address ranges; else false. + * @param string $ip IP address in network address format + * @param array $ipRanges List of IP address ranges + * @return bool True if in any of the specified IP address ranges; else false. */ static public function isIpInRange($ip, $ipRanges) { @@ -353,7 +353,7 @@ class Piwik_IP * Returns the best possible IP of the current user, in the format A.B.C.D * For example, this could be the proxy client's IP address. * - * @return string IP address in presentation format + * @return string IP address in presentation format */ static public function getIpFromHeader() { @@ -376,8 +376,8 @@ class Piwik_IP /** * Returns a non-proxy IP address from header * - * @param string $default Default value to return if no matching proxy header - * @param array $proxyHeaders List of proxy headers + * @param string $default Default value to return if no matching proxy header + * @param array $proxyHeaders List of proxy headers * @return string */ static public function getNonProxyIpFromHeader($default, $proxyHeaders) @@ -408,9 +408,9 @@ class Piwik_IP /** * Returns the last IP address in a comma separated list, subject to an optional exclusion list. * - * @param string $csv Comma separated list of elements - * @param array $excludedIps Optional list of excluded IP addresses (or IP address ranges) - * @return string Last (non-excluded) IP address in the list + * @param string $csv Comma separated list of elements + * @param array $excludedIps Optional list of excluded IP addresses (or IP address ranges) + * @return string Last (non-excluded) IP address in the list */ static public function getLastIpFromList($csv, $excludedIps = null) { @@ -433,8 +433,8 @@ class Piwik_IP /** * Get hostname for a given IP address * - * @param string $ipStr Human-readable IP address - * @return string Hostname or unmodified $ipStr if failure + * @param string $ipStr Human-readable IP address + * @return string Hostname or unmodified $ipStr if failure */ static public function getHostByAddr($ipStr) { @@ -450,8 +450,8 @@ class Piwik_IP * * @link http://php.net/inet_ntop * - * @param string $in_addr 32-bit IPv4 or 128-bit IPv6 address - * @return string|false string representation of address or false on failure + * @param string $in_addr 32-bit IPv4 or 128-bit IPv6 address + * @return string|false string representation of address or false on failure */ function php_compat_inet_ntop($in_addr) { @@ -523,8 +523,8 @@ function php_compat_inet_ntop($in_addr) * * @link http://php.net/inet_pton * - * @param string $address a human readable IPv4 or IPv6 address - * @return string in_addr representation or false on failure + * @param string $address a human readable IPv4 or IPv6 address + * @return string in_addr representation or false on failure */ function php_compat_inet_pton($address) { diff --git a/core/Mail.php b/core/Mail.php index 1abe8f0cb3..8c1fa3c2e8 100644 --- a/core/Mail.php +++ b/core/Mail.php @@ -21,14 +21,21 @@ class Piwik_Mail extends Zend_Mail { /** * Default charset utf-8 - * @param string $charset + * + * @param string $charset charset, defaults to utf-8 */ public function __construct($charset = 'utf-8') { parent::__construct($charset); $this->initSmtpTransport(); } - + + /** + * Sets the sender to use + * + * @param string $email + * @param null|string $name + */ public function setFrom($email, $name = null) { $hostname = Piwik_Config::getInstance()->mail['defaultHostnameIfEmpty']; @@ -46,7 +53,10 @@ class Piwik_Mail extends Zend_Mail $email = str_replace('{DOMAIN}', $piwikHost, $email); parent::setFrom($email, $name); } - + + /** + * @return void + */ private function initSmtpTransport() { $mailConfig = Piwik_Config::getInstance()->mail; diff --git a/core/Nonce.php b/core/Nonce.php index 1acd4c7464..33d1c24d55 100644 --- a/core/Nonce.php +++ b/core/Nonce.php @@ -28,9 +28,9 @@ class Piwik_Nonce /** * Generate nonce * - * @param string $id Unique id to avoid namespace conflicts, e.g., ModuleName.ActionName - * @param int $ttl Optional time-to-live in seconds; default is 5 minutes - * @return string Nonce + * @param string $id Unique id to avoid namespace conflicts, e.g., ModuleName.ActionName + * @param int $ttl Optional time-to-live in seconds; default is 5 minutes + * @return string Nonce */ static public function getNonce($id, $ttl = 300) { @@ -54,9 +54,9 @@ class Piwik_Nonce /** * Verify nonce and check referrer (if present, i.e., it may be suppressed by the browser or a proxy/network). * - * @param string $id Unique id - * @param string $cnonce Nonce sent to client - * @return bool true if valid; false otherwise + * @param string $id Unique id + * @param string $cnonce Nonce sent to client + * @return bool true if valid; false otherwise */ static public function verifyNonce($id, $cnonce) { @@ -91,7 +91,7 @@ class Piwik_Nonce /** * Discard nonce ("now" as opposed to waiting for garbage collection) * - * @param string $id Unique id + * @param string $id Unique id */ static public function discardNonce($id) { diff --git a/core/Option.php b/core/Option.php index cb3b5d64c9..85dd07ffee 100644 --- a/core/Option.php +++ b/core/Option.php @@ -20,13 +20,24 @@ */ class Piwik_Option { + /** + * @var array + */ private $all = array(); + + /** + * @var bool + */ private $loaded = false; + /** + * Singleton instance + * @var self + */ static private $instance = null; /** - * Singleton + * Returns Singleton instance * * @return Piwik_Option */ @@ -38,14 +49,17 @@ class Piwik_Option } return self::$instance; } - + + /** + * Private Constructor + */ private function __construct() {} /** * Returns the option value for the requested option $name, fetching from database, if not in cache. * - * @param string $name Key - * @return string|false Value or false, if not found + * @param string $name Key + * @return string|false Value or false, if not found */ public function get($name) { @@ -68,9 +82,9 @@ class Piwik_Option /** * Sets the option value in the database and cache * - * @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 + * @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. */ public function set($name, $value, $autoload = 0) { @@ -85,8 +99,8 @@ class Piwik_Option /** * Delete key-value pair from database and reload cache. * - * @param string $name Key to match exactly - * @param string $value Optional value + * @param string $name Key to match exactly + * @param string $value Optional value */ public function delete($name, $value = null) { @@ -108,8 +122,8 @@ class Piwik_Option * Delete key-value pair(s) from database and reload cache. * The supplied pattern should use '%' as wildcards, and literal '_' should be escaped. * - * @param string $name Pattern of key to match. - * @param string $value Optional value + * @param string $name Pattern of key to match. + * @param string $value Optional value */ public function deleteLike($name, $value = null) { @@ -129,7 +143,8 @@ class Piwik_Option /** * Initialize cache with autoload settings. - * @return + * + * @return void */ private function autoload() { @@ -165,8 +180,8 @@ class Piwik_Option /** * Returns the option value for the requested option $name * - * @param string $name Key - * @return string|false Value or false, if not found + * @param string $name Key + * @return string|false Value or false, if not found */ function Piwik_GetOption($name) { @@ -176,9 +191,9 @@ function Piwik_GetOption($name) /** * Sets the option value in the database * - * @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 + * @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. */ function Piwik_SetOption($name, $value, $autoload = 0) { diff --git a/core/Piwik.php b/core/Piwik.php index 0eef3b8beb..80f79ed183 100644 --- a/core/Piwik.php +++ b/core/Piwik.php @@ -25,10 +25,10 @@ class Piwik const CLASSES_PREFIX = 'Piwik_'; const COMPRESSED_FILE_LOCATION = '/tmp/assets/'; -/* - * Piwik periods - */ - + /* + * Piwik periods + * @var arrray + */ public static $idPeriods = array( 'day' => 1, 'week' => 2, @@ -42,7 +42,7 @@ class Piwik * -> Always process for day/week/month periods * For Year and Range, only process if it was enabled in the config file, * - * @param string $periodLabel Period label (e.g., 'day') + * @param string $periodLabel Period label (e.g., 'day') * @return bool */ static public function isUniqueVisitorsEnabled($periodLabel) @@ -50,15 +50,11 @@ class Piwik $settingName = "enable_processing_unique_visitors_$periodLabel"; return Piwik_Config::getInstance()->General[$settingName] == 1; } - -/* - * Prefix/unprefix class name - */ /** * Prefix class name (if needed) * - * @param string $class + * @param string $class * @return string */ static public function prefixClass( $class ) @@ -73,7 +69,7 @@ class Piwik /** * Unprefix class name (if needed) * - * @param string $class + * @param string $class * @return string */ static public function unprefixClass( $class ) @@ -86,10 +82,6 @@ class Piwik return $class; } -/* - * Installation / Uninstallation - */ - /** * Installation helper */ @@ -111,7 +103,7 @@ class Piwik * * @since 0.6.3 * - * @return bool True if installed; false otherwise + * @return bool True if installed; false otherwise */ static public function isInstalled() { @@ -138,6 +130,7 @@ class Piwik * If not found, then tries to cache it and returns the value. * * If the Piwik URL changes (eg. Piwik moved to new server), the value will automatically be refreshed in the cache. + * * @return string */ static public function getPiwikUrl() @@ -183,7 +176,7 @@ class Piwik /** * Set response header, e.g., HTTP/1.0 200 Ok * - * @param string $status Status + * @param string $status Status * @return bool */ static public function setHttpStatus($status) @@ -210,7 +203,7 @@ class Piwik * @see http://support.microsoft.com/kb/316431/ * @see RFC2616 * - * @param string $override One of "public", "private", "no-cache", or "no-store". (optional) + * @param string $override One of "public", "private", "no-cache", or "no-store". (optional) */ static public function overrideCacheControlHeaders($override = null) { @@ -236,9 +229,9 @@ class Piwik /** * Copy recursively from $source to $target. * - * @param string $source eg. './tmp/latest' - * @param string $target eg. '.' - * @param bool $excludePhp + * @param string $source eg. './tmp/latest' + * @param string $target eg. '.' + * @param bool $excludePhp */ static public function copyRecursive($source, $target, $excludePhp=false ) { @@ -273,9 +266,9 @@ class Piwik /** * Copy individual file from $source to $target. * - * @param string $source eg. './tmp/latest/index.php' - * @param string $dest eg. './index.php' - * @param bool $excludePhp + * @param string $source eg. './tmp/latest/index.php' + * @param string $dest eg. './index.php' + * @param bool $excludePhp * @throws Exception * @return bool */ @@ -308,8 +301,8 @@ class Piwik /** * Returns friendly error message explaining how to fix permissions * - * @param $path to the directory missing permissions - * @return string Error message + * @param string $path to the directory missing permissions + * @return string Error message */ static public function getErrorMessageMissingPermissions($path) { @@ -335,8 +328,8 @@ class Piwik /** * Recursively delete a directory * - * @param string $dir Directory name - * @param boolean $deleteRootToo Delete specified top-level directory as well + * @param string $dir Directory name + * @param boolean $deleteRootToo Delete specified top-level directory as well */ static public function unlinkRecursive($dir, $deleteRootToo) { @@ -368,9 +361,9 @@ class Piwik * Recursively find pathnames that match a pattern * @see glob() * - * @param string $sDir directory - * @param string $sPattern pattern - * @param int $nFlags glob() flags + * @param string $sDir directory + * @param string $sPattern pattern + * @param int $nFlags glob() flags * @return array */ public static function globr($sDir, $sPattern, $nFlags = NULL) @@ -393,7 +386,7 @@ class Piwik /** * Returns the help text displayed to suggest which command to run to give writable access to a file or directory * - * @param string $realpath + * @param string $realpath * @return string */ static private function getMakeWritableCommand($realpath) @@ -409,7 +402,7 @@ class Piwik * Checks that the directories Piwik needs write access are actually writable * Displays a nice error page if permissions are missing on some directories * - * @param array $directoriesToCheck Array of directory names to check + * @param array $directoriesToCheck Array of directory names to check */ static public function checkDirectoriesWritableOrDie( $directoriesToCheck = null ) { @@ -450,8 +443,8 @@ class Piwik /** * Checks if directories are writable and create them if they do not exist. * - * @param array $directoriesToCheck array of directories to check - if not given default Piwik directories that needs write permission are checked - * @return array directory name => true|false (is writable) + * @param array $directoriesToCheck array of directories to check - if not given default Piwik directories that needs write permission are checked + * @return array directory name => true|false (is writable) */ static public function checkDirectoriesWritable($directoriesToCheck = null) { @@ -495,8 +488,8 @@ class Piwik /** * Check if this installation can be auto-updated. - * * For performance, we look for clues rather than an exhaustive test. + * * @return bool */ static public function canAutoUpdate() @@ -723,7 +716,7 @@ class Piwik /** * Test if php output is compressed * - * @return bool True if php output is (or suspected/likely) to be compressed + * @return bool True if php output is (or suspected/likely) to be compressed */ static public function isPhpOutputCompressed() { @@ -770,10 +763,10 @@ class Piwik * A future upgrade of this method would be to recreate the directory structure of the static file * within a /tmp/compressed-static-files directory. * - * @param string $file The location of the static file to serve - * @param string $contentType The content type of the static file. - * @param bool $expireFarFuture If set to true, will set Expires: header in far future. - * Should be set to false for files that don't have a cache buster (eg. piwik.js) + * @param string $file The location of the static file to serve + * @param string $contentType The content type of the static file. + * @param bool $expireFarFuture If set to true, will set Expires: header in far future. + * Should be set to false for files that don't have a cache buster (eg. piwik.js) */ static public function serveStaticFile($file, $contentType, $expireFarFuture = true) { @@ -904,10 +897,10 @@ class Piwik /** * Create CSV (or other delimited) files * - * @param string $filePath - * @param array $fileSpec File specifications (delimiter, line terminator, etc) - * @param array $rows Array of array corresponding to rows of values - * @throws Exception if unable to create or write to file + * @param string $filePath filename to create + * @param array $fileSpec File specifications (delimiter, line terminator, etc) + * @param array $rows Array of array corresponding to rows of values + * @throws Exception if unable to create or write to file */ static public function createCSVFile($filePath, $fileSpec, $rows) { @@ -960,7 +953,7 @@ class Piwik /** * Set maximum script execution time. * - * @param int max execution time in seconds (0 = no limit) + * @param int $executionTime max execution time in seconds (0 = no limit) */ static public function setMaxExecutionTime($executionTime) { @@ -976,7 +969,7 @@ class Piwik * compile-time default, so ini_get('memory_limit') may return false. * * @see http://www.php.net/manual/en/faq.using.php#faq.using.shorthandbytes - * @return int|false memory limit in megabytes, or false if there is no limit + * @return int|false memory limit in megabytes, or false if there is no limit */ static public function getMemoryLimitValue() { @@ -1008,8 +1001,8 @@ class Piwik * * Note: system settings may prevent scripts from overriding the master value * - * @param int $minimumMemoryLimit - * @return bool true if set; false otherwise + * @param int $minimumMemoryLimit + * @return bool true if set; false otherwise */ static public function setMemoryLimit($minimumMemoryLimit) { @@ -1026,7 +1019,7 @@ class Piwik /** * Raise PHP memory limit if below the minimum required * - * @return bool true if set; false otherwise + * @return bool true if set; false otherwise */ static public function raiseMemoryLimitIfNecessary() { @@ -1063,7 +1056,7 @@ class Piwik /** * Log a message * - * @param string $message + * @param string $message */ static public function log($message = '') { @@ -1086,6 +1079,10 @@ class Piwik } } + /** + * Returns if logging should work + * @return bool + */ static public function shouldLoggerLog() { try { @@ -1104,7 +1101,7 @@ class Piwik /** * Trigger E_USER_ERROR with optional message * - * @param string $message + * @param string $message */ static public function error($message = '') { @@ -1115,7 +1112,7 @@ class Piwik * Display the message in a nice red font with a nice icon * ... and dies * - * @param string $message + * @param string $message */ static public function exitWithErrorMessage( $message ) { @@ -1135,7 +1132,7 @@ class Piwik /** * Get total number of queries * - * @return int number of queries + * @return int number of queries */ static public function getQueryCount() { @@ -1146,7 +1143,7 @@ class Piwik /** * Get total elapsed time (in seconds) * - * @return int elapsed time + * @return int elapsed time */ static public function getDbElapsedSecs() { @@ -1167,7 +1164,7 @@ class Piwik /** * Print profiling report for the tracker * - * @param Piwik_Tracker_Db $db Tracker database object (or null) + * @param Piwik_Tracker_Db $db Tracker database object (or null) */ static public function printSqlProfilingReportTracker( $db = null ) { @@ -1206,6 +1203,7 @@ class Piwik /** * Outputs SQL Profiling reports * It is automatically called when enabling the SQL profiling in the config file enable_sql_profiler + * @throws Exception */ static function printSqlProfilingReportZend() { @@ -1263,7 +1261,7 @@ class Piwik /** * Log a breakdown by query * - * @param array $infoIndexedByQuery + * @param array $infoIndexedByQuery */ static private function getSqlProfilingQueryBreakdownOutput( $infoIndexedByQuery ) { @@ -1295,8 +1293,8 @@ class Piwik /** * Print memory leak * - * @param string $prefix - * @param string $suffix + * @param string $prefix + * @param string $suffix */ static public function printMemoryLeak($prefix = '', $suffix = '<br />') { @@ -1336,7 +1334,7 @@ class Piwik /** * Returns a list of currency symbols * - * @return array array( currencyCode => symbol, ... ) + * @return array array( currencyCode => symbol, ... ) */ static public function getCurrencyList() { @@ -1353,9 +1351,9 @@ class Piwik * Computes the division of i1 by i2. If either i1 or i2 are not number, or if i2 has a value of zero * we return 0 to avoid the division by zero. * - * @param numeric $i1 - * @param numeric $i2 - * @return numeric The result of the division or zero + * @param number $i1 + * @param number $i2 + * @return number The result of the division or zero */ static public function secureDiv( $i1, $i2 ) { @@ -1369,10 +1367,10 @@ class Piwik /** * Safely compute a percentage. Return 0 to avoid division by zero. * - * @param numeric $dividend - * @param numeric $divisor - * @param int $precision - * @return numeric + * @param number $dividend + * @param number $divisor + * @param int $precision + * @return number */ static public function getPercentageSafe($dividend, $divisor, $precision = 0) { @@ -1386,7 +1384,7 @@ class Piwik /** * Get currency symbol for a site * - * @param int $idSite + * @param int $idSite * @return string */ static public function getCurrency($idSite) @@ -1404,11 +1402,11 @@ class Piwik /** * For the given value, based on the column name, will apply: pretty time, pretty money - * @param int $idSite - * @param string $columnName - * @param mixed $value - * @param bool $htmlAllowed - * @param string $timeAsSentence + * @param int $idSite + * @param string $columnName + * @param mixed $value + * @param bool $htmlAllowed + * @param string $timeAsSentence * @return string */ static public function getPrettyValue($idSite, $columnName, $value, $htmlAllowed, $timeAsSentence) @@ -1437,9 +1435,9 @@ class Piwik /** * Pretty format monetary value for a site * - * @param int|string $value - * @param int $idSite - * @param bool $htmlAllowed + * @param int|string $value + * @param int $idSite + * @param bool $htmlAllowed * @return string */ static public function getPrettyMoney($value, $idSite, $htmlAllowed = true) @@ -1483,9 +1481,9 @@ class Piwik /** * Pretty format a memory size value * - * @param numeric $size in bytes - * @param string $unit The specific unit to use, if any. If null, the unit is determined by $size. - * @param int $precision The precision to use when rounding. + * @param number $size size in bytes + * @param string $unit The specific unit to use, if any. If null, the unit is determined by $size. + * @param int $precision The precision to use when rounding. * @return string */ static public function getPrettySizeFromBytes( $size, $unit = null, $precision = 1 ) @@ -1513,9 +1511,9 @@ class Piwik /** * Pretty format a time * - * @param int $numberOfSeconds - * @param bool $displayTimeAsSentence If set to true, will output "5min 17s", if false "00:05:17" - * @param bool $isHtml + * @param int $numberOfSeconds + * @param bool $displayTimeAsSentence If set to true, will output "5min 17s", if false "00:05:17" + * @param bool $isHtml * @return string */ static public function getPrettyTimeFromSeconds($numberOfSeconds, $displayTimeAsSentence = true, $isHtml = true) @@ -1574,7 +1572,7 @@ class Piwik * Gets a prettified string representation of a number. The result will have * thousands separators and a decimal point specific to the current locale. * - * @param numeric $value + * @param number $value * @return string */ static public function getPrettyNumber( $value ) @@ -1590,8 +1588,8 @@ class Piwik /** * Returns the Javascript code to be inserted on every page to track * - * @param int $idSite - * @param string $piwikUrl http://path/to/piwik/directory/ + * @param int $idSite + * @param string $piwikUrl http://path/to/piwik/directory/ * @return string */ static public function getJavascriptCode($idSite, $piwikUrl) @@ -1642,6 +1640,7 @@ class Piwik /** * Segments to pre-process + * * @return string */ static public function getKnownSegmentsToArchive() @@ -1690,7 +1689,7 @@ class Piwik /** * Get current user login * - * @return string login ID + * @return string login ID */ static public function getCurrentUserLogin() { @@ -1700,7 +1699,7 @@ class Piwik /** * Get current user's token auth * - * @return string Token auth + * @return string Token auth */ static public function getCurrentUserTokenAuth() { @@ -1711,7 +1710,7 @@ class Piwik * Returns true if the current user is either the super user, or the user $theUser * Used when modifying user preference: this usually requires super user or being the user itself. * - * @param string $theUser + * @param string $theUser * @return bool */ static public function isUserIsSuperUserOrTheUser( $theUser ) @@ -1727,8 +1726,8 @@ class Piwik /** * Check that current user is either the specified user or the superuser * - * @param string $theUser - * @throws exception if the user is neither the super user nor the user $theUser + * @param string $theUser + * @throws Piwik_Access_NoAccessException if the user is neither the super user nor the user $theUser */ static public function checkUserIsSuperUserOrTheUser( $theUser ) { @@ -1761,7 +1760,7 @@ class Piwik /** * Is user the anonymous user? * - * @return bool True if anonymouse; false otherwise + * @return bool True if anonymouse; false otherwise */ static public function isUserIsAnonymous() { @@ -1771,7 +1770,7 @@ class Piwik /** * Checks if user is not the anonymous user. * - * @throws Exception if user is anonymous. + * @throws Piwik_Access_NoAccessException if user is anonymous. */ static public function checkUserIsNotAnonymous() { @@ -1785,7 +1784,7 @@ class Piwik * Helper method user to set the current as Super User. * This should be used with great care as this gives the user all permissions. * - * @param bool $bool true to set current user as super user + * @param bool $bool true to set current user as super user */ static public function setUserIsSuperUser( $bool = true ) { @@ -1805,7 +1804,7 @@ class Piwik /** * Returns true if the user has admin access to the sites * - * @param mixed $idSites + * @param mixed $idSites * @return bool */ static public function isUserHasAdminAccess( $idSites ) @@ -1821,7 +1820,7 @@ class Piwik /** * Check user has admin access to the sites * - * @param mixed $idSites + * @param mixed $idSites * @throws Exception if user doesn't have admin access to the sites */ static public function checkUserHasAdminAccess( $idSites ) @@ -1857,7 +1856,7 @@ class Piwik /** * Returns true if the user has view access to the sites * - * @param mixed $idSites + * @param mixed $idSites * @return bool */ static public function isUserHasViewAccess( $idSites ) @@ -1873,7 +1872,7 @@ class Piwik /** * Check user has view access to the sites * - * @param mixed $idSites + * @param mixed $idSites * @throws Exception if user doesn't have view access to sites */ static public function checkUserHasViewAccess( $idSites ) @@ -1958,7 +1957,7 @@ class Piwik * array[]=value1&array[]=value2 in the URL. * This function will handle both cases and return the array. * - * @param array|string $columns String or array + * @param array|string $columns * @return array */ static public function getArrayFromApiParameter($columns) @@ -1974,10 +1973,10 @@ class Piwik /** * Redirect to module (and action) * - * @param string $newModule Target module - * @param string $newAction Target action - * @param array $parameters Parameters to modify in the URL - * @return bool false if the URL to redirect to is already this URL + * @param string $newModule Target module + * @param string $newAction Target action + * @param array $parameters Parameters to modify in the URL + * @return bool false if the URL to redirect to is already this URL */ static public function redirectToModule( $newModule, $newAction = '', $parameters = array() ) { @@ -1994,7 +1993,7 @@ class Piwik /** * Create database object and connect to database - * @param array $dbInfos + * @param array|null $dbInfos */ static public function createDatabaseObject( $dbInfos = null ) { @@ -2043,7 +2042,7 @@ class Piwik /** * Check database connection character set is utf8. * - * @return bool True if it is (or doesn't matter); false otherwise + * @return bool True if it is (or doesn't matter); false otherwise */ static public function isDatabaseConnectionUTF8() { @@ -2056,6 +2055,7 @@ class Piwik /** * Create log object + * @throws Exception */ static public function createLogObject() { @@ -2144,7 +2144,7 @@ class Piwik /** * Returns true if the email is a valid email * - * @param string email + * @param string $email * @return bool */ static public function isValidEmailString( $email ) @@ -2156,9 +2156,9 @@ class Piwik * Returns true if the login is valid. * Warning: does not check if the login already exists! You must use UsersManager_API->userExists as well. * - * @param $userLogin + * @param string $userLogin * @throws Exception - * @return bool or throws exception + * @return bool */ static public function checkValidLoginString( $userLogin ) { @@ -2182,7 +2182,7 @@ class Piwik /** * Should Piwik check that the login & password have minimum length and valid characters? * - * @return bool True if checks enabled; false otherwise + * @return bool True if checks enabled; false otherwise */ static public function isChecksEnabled() { @@ -2214,7 +2214,7 @@ class Piwik * (e.g., php >= 5.2, or compiled with EXPERIMENTAL_DATE_SUPPORT=1 for * php < 5.2). * - * @return bool True if timezones supported; false otherwise + * @return bool True if timezones supported; false otherwise */ static public function isTimezoneSupportEnabled() { @@ -2233,7 +2233,7 @@ class Piwik /** * Is the schema available? * - * @return bool True if schema is available; false otherwise + * @return bool True if schema is available; false otherwise */ static public function isAvailable() { @@ -2243,8 +2243,8 @@ class Piwik /** * Get the SQL to create a specific Piwik table * - * @param string $tableName - * @return string SQL + * @param string $tableName + * @return string SQL */ static public function getTableCreateSql( $tableName ) { @@ -2254,7 +2254,7 @@ class Piwik /** * Get the SQL to create Piwik tables * - * @return array of strings containing SQL + * @return array array of strings containing SQL */ static public function getTablesCreateSql() { @@ -2264,7 +2264,7 @@ class Piwik /** * Create database * - * @param string $dbName + * @param string|null $dbName */ static public function createDatabase( $dbName = null ) { @@ -2306,7 +2306,7 @@ class Piwik /** * Drop specific tables * - * @param array $doNotDelete Names of tables to not delete + * @param array $doNotDelete Names of tables to not delete */ static public function dropTables( $doNotDelete = array() ) { @@ -2317,7 +2317,7 @@ class Piwik * Names of all the prefixed tables in piwik * Doesn't use the DB * - * @return array Table names + * @return array Table names */ static public function getTablesNames() { @@ -2327,8 +2327,8 @@ class Piwik /** * Get list of tables installed * - * @param bool $forceReload Invalidate cache - * @return array Tables installed + * @param bool $forceReload Invalidate cache + * @return array Tables installed */ static public function getTablesInstalled($forceReload = true) { @@ -2338,11 +2338,11 @@ class Piwik /** * Batch insert into table from CSV (or other delimited) file. * - * @param string $tableName Name of table - * @param array $fields Field names - * @param string $filePath Path name of a file. - * @param array $fileSpec File specifications (delimiter, line terminator, etc) - * @return bool True if successful; false otherwise + * @param string $tableName Name of table + * @param array $fields Field names + * @param string $filePath Path name of a file. + * @param array $fileSpec File specifications (delimiter, line terminator, etc) + * @return bool True if successful; false otherwise */ static public function createTableFromCSVFile($tableName, $fields, $filePath, $fileSpec) { @@ -2425,10 +2425,11 @@ class Piwik * Performs a batch insert into a specific table using either LOAD DATA INFILE or plain INSERTs, * as a fallback. On MySQL, LOAD DATA INFILE is 20x faster than a series of plain INSERTs. * - * @param string $tableName PREFIXED table name! you must call Piwik_Common::prefixTable() before passing the table name - * @param array $fields array of unquoted field names - * @param array $values array of data to be inserted - * @return bool True if the bulk LOAD was used, false if we fallback to plain INSERTs + * @param string $tableName PREFIXED table name! you must call Piwik_Common::prefixTable() before passing the table name + * @param array $fields array of unquoted field names + * @param array $values array of data to be inserted + * @throws Exception + * @return bool True if the bulk LOAD was used, false if we fallback to plain INSERTs */ static public function tableInsertBatch($tableName, $fields, $values) { @@ -2481,10 +2482,10 @@ class Piwik * * NOTE: you should use tableInsertBatch() which will fallback to this function if LOAD DATA INFILE not available * - * @param string $tableName PREFIXED table name! you must call Piwik_Common::prefixTable() before passing the table name - * @param array $fields array of unquoted field names - * @param array $values array of data to be inserted - * @param bool $ignoreWhenDuplicate Ignore new rows that contain unique key values that duplicate old rows + * @param string $tableName PREFIXED table name! you must call Piwik_Common::prefixTable() before passing the table name + * @param array $fields array of unquoted field names + * @param array $values array of data to be inserted + * @param bool $ignoreWhenDuplicate Ignore new rows that contain unique key values that duplicate old rows */ static public function tableInsertBatchIterate($tableName, $fields, $values, $ignoreWhenDuplicate = true) { @@ -2503,9 +2504,9 @@ class Piwik /** * Generate advisory lock name * - * @param int $idsite - * @param Piwik_Period $period - * @param Piwik_Segment $segment + * @param int $idsite + * @param Piwik_Period $period + * @param Piwik_Segment $segment * @return string */ static public function getArchiveProcessingLockName($idsite, $period, Piwik_Segment $segment) @@ -2526,10 +2527,10 @@ class Piwik /** * Get an advisory lock * - * @param int $idsite - * @param Piwik_Period $period - * @param Piwik_Segment $segment - * @return bool True if lock acquired; false otherwise + * @param int $idsite + * @param Piwik_Period $period + * @param Piwik_Segment $segment + * @return bool True if lock acquired; false otherwise */ static public function getArchiveProcessingLock($idsite, $period, $segment) { @@ -2559,9 +2560,9 @@ class Piwik /** * Release an advisory lock * - * @param int $idsite - * @param Piwik_Period $period - * @param Piwik_Segment $segment + * @param int $idsite + * @param Piwik_Period $period + * @param Piwik_Segment $segment * @return bool True if lock released; false otherwise */ static public function releaseArchiveProcessingLock($idsite, $period, $segment) diff --git a/core/Plugin.php b/core/Plugin.php index 9770523f73..e20a156d27 100644 --- a/core/Plugin.php +++ b/core/Plugin.php @@ -29,11 +29,14 @@ abstract class Piwik_Plugin * - 'version' => string // plugin version number; examples and 3rd party plugins must not use Piwik_Version::VERSION; 3rd party plugins must increment the version number with each plugin release * - 'translationAvailable' => bool // is there a translation file in plugins/your-plugin/lang/* ? * - 'TrackerPlugin' => bool // should we load this plugin during the stats logging process? + * + * @return array */ abstract public function getInformation(); /** * Returns the list of hooks registered with the methods names + * * @return array */ public function getListHooksRegistered() diff --git a/core/PluginsFunctions/WidgetsList.php b/core/PluginsFunctions/WidgetsList.php index 21234832f4..5fef64028c 100644 --- a/core/PluginsFunctions/WidgetsList.php +++ b/core/PluginsFunctions/WidgetsList.php @@ -15,10 +15,27 @@ */ class Piwik_WidgetsList { + /** + * List of widgets + * + * @var array + */ static protected $widgets = null; + + /** + * Indicated whether the hook was posted or not + * + * @var bool + */ static protected $hookCalled = false; - - static function get() + + /** + * Returns all available widgets + * The event WidgetsList.add is used to create the list + * + * @return array + */ + static public function get() { if(!self::$hookCalled) { @@ -27,8 +44,17 @@ class Piwik_WidgetsList } return self::$widgets; } - - static function add($widgetCategory, $widgetName, $controllerName, $controllerAction, $customParameters) + + /** + * Adds an widget to the list + * + * @param string $widgetCategory + * @param string $widgetName + * @param string $controllerName + * @param string $controllerAction + * @param array $customParameters + */ + static public function add($widgetCategory, $widgetName, $controllerName, $controllerAction, $customParameters) { $widgetCategory = Piwik_Translate($widgetCategory); $widgetName = Piwik_Translate($widgetName); @@ -51,8 +77,15 @@ class Piwik_WidgetsList ) + $customParameters ); } - - static function isDefined($controllerName, $controllerAction) + + /** + * Checks if the widget with the given parameters exists in der widget list + * + * @param string $controllerName + * @param string $controllerAction + * @return bool + */ + static public function isDefined($controllerName, $controllerAction) { $widgetsList = self::get(); foreach($widgetsList as $widgetCategory => $widgets) @@ -70,16 +103,43 @@ class Piwik_WidgetsList } } +/** + * Returns all available widgets + * + * @see Piwik_WidgetsList::get + * + * @return array + */ function Piwik_GetWidgetsList() { return Piwik_WidgetsList::get(); } +/** + * Adds an widget to the list + * + * @see Piwik_WidgetsList::add + * + * @param string $widgetCategory + * @param string $widgetName + * @param string $controllerName + * @param string $controllerAction + * @param array $customParameters + */ function Piwik_AddWidget( $widgetCategory, $widgetName, $controllerName, $controllerAction, $customParameters = array()) { Piwik_WidgetsList::add($widgetCategory, $widgetName, $controllerName, $controllerAction, $customParameters); } +/** + * Checks if the widget with the given parameters exists in der widget list + * + * @see Piwik_WidgetsList::isDefined + * + * @param string $controllerName + * @param string $controllerAction + * @return bool + */ function Piwik_IsWidgetDefined($controllerName, $controllerAction) { return Piwik_WidgetsList::isDefined($controllerName, $controllerAction); diff --git a/core/PluginsManager.php b/core/PluginsManager.php index 581f35bc94..da1f555ea0 100644 --- a/core/PluginsManager.php +++ b/core/PluginsManager.php @@ -81,7 +81,7 @@ class Piwik_PluginsManager /** * Returns true if plugin is always activated * - * @param string $name Name of plugin + * @param string $name Name of plugin * @return bool */ public function isPluginAlwaysActivated( $name ) @@ -92,7 +92,7 @@ class Piwik_PluginsManager /** * Returns true if plugin has been activated * - * @param string $name Name of plugin + * @param string $name Name of plugin * @return bool */ public function isPluginActivated( $name ) @@ -104,7 +104,7 @@ class Piwik_PluginsManager /** * Returns true if plugin is loaded (in memory) * - * @param string $name Name of plugin + * @param string $name Name of plugin * @return bool */ public function isPluginLoaded( $name ) @@ -127,7 +127,7 @@ class Piwik_PluginsManager /** * Deactivate plugin * - * @param string $pluginName Name of plugin + * @param string $pluginName Name of plugin */ public function deactivatePlugin($pluginName) { @@ -173,7 +173,7 @@ class Piwik_PluginsManager /** * Activate the specified plugin and install (if needed) * - * @param string $pluginName Name of plugin + * @param string $pluginName Name of plugin * @throws Exception */ public function activatePlugin($pluginName) @@ -216,7 +216,7 @@ class Piwik_PluginsManager /** * Load the specified plugins * - * @param array $pluginsToLoad Array of plugins to load + * @param array $pluginsToLoad Array of plugins to load */ public function loadPlugins( array $pluginsToLoad ) { @@ -248,7 +248,7 @@ class Piwik_PluginsManager /** * Load translations for loaded plugins * - * @param bool|string $language Optional language code + * @param bool|string $language Optional language code */ public function loadPluginTranslations($language = false) { @@ -304,9 +304,9 @@ class Piwik_PluginsManager /** * Returns the given Piwik_Plugin object * - * @param string $name + * @param string $name * @throws Exception - * @return Piwik_Piwik + * @return array */ public function getLoadedPlugin($name) { @@ -348,7 +348,7 @@ class Piwik_PluginsManager * Loads the plugin filename and instantiates the plugin with the given name, eg. UserCountry * Do NOT give the class name ie. Piwik_UserCountry, but give the plugin name ie. UserCountry * - * @param string $pluginName + * @param string $pluginName * @throws Exception * @return Piwik_Plugin */ @@ -397,7 +397,7 @@ class Piwik_PluginsManager /** * Unload plugin * - * @param Piwik_Plugin $plugin + * @param Piwik_Plugin $plugin * @throws Exception */ public function unloadPlugin( $plugin ) @@ -445,7 +445,7 @@ class Piwik_PluginsManager /** * Install a specific plugin * - * @param Piwik_Plugin $plugin + * @param Piwik_Plugin $plugin * @throws Piwik_PluginsManager_PluginException if installation fails */ private function installPlugin( Piwik_Plugin $plugin ) @@ -460,7 +460,7 @@ class Piwik_PluginsManager /** * For the given plugin, add all the observers of this plugin. * - * @param Piwik_Plugin $plugin + * @param Piwik_Plugin $plugin */ private function addPluginObservers( Piwik_Plugin $plugin ) { @@ -475,8 +475,8 @@ class Piwik_PluginsManager /** * Add a plugin in the loaded plugins array * - * @param string $pluginName plugin name without prefix (eg. 'UserCountry') - * @param Piwik_Plugin $newPlugin + * @param string $pluginName plugin name without prefix (eg. 'UserCountry') + * @param Piwik_Plugin $newPlugin */ private function addLoadedPlugin( $pluginName, Piwik_Plugin $newPlugin ) { @@ -486,8 +486,10 @@ class Piwik_PluginsManager /** * Load translation * - * @param Piwik_Plugin $plugin - * @param string $langCode + * @param Piwik_Plugin $plugin + * @param string $langCode + * @throws Exception + * @return void */ private function loadTranslation( $plugin, $langCode ) { @@ -547,7 +549,7 @@ class Piwik_PluginsManager /** * Install a plugin, if necessary * - * @param Piwik_Plugin $plugin + * @param Piwik_Plugin $plugin */ private function installPluginIfNecessary( Piwik_Plugin $plugin ) { @@ -611,11 +613,11 @@ class Piwik_PluginsManager_PluginException extends Exception /** * Post an event to the dispatcher which will notice the observers * - * @param string $eventName The event name - * @param mixed $object Object, array or string that the listeners can read and/or modify. - * Listeners can call $object =& $notification->getNotificationObject(); to fetch and then modify this variable. - * @param array $info Additional array of data that can be used by the listeners, but not edited - * @param bool $pending Should the notification be posted to plugins that register after the notification was sent? + * @param string $eventName The event name + * @param mixed $object Object, array or string that the listeners can read and/or modify. + * Listeners can call $object =& $notification->getNotificationObject(); to fetch and then modify this variable. + * @param array $info Additional array of data that can be used by the listeners, but not edited + * @param bool $pending Should the notification be posted to plugins that register after the notification was sent? * @return void */ function Piwik_PostEvent( $eventName, &$object = null, $info = array(), $pending = false ) @@ -627,8 +629,8 @@ function Piwik_PostEvent( $eventName, &$object = null, $info = array(), $pendin /** * Register an action to execute for a given event * - * @param string $hookName Name of event - * @param function $function Callback hook + * @param string $hookName Name of event + * @param function $function Callback hook */ function Piwik_AddAction( $hookName, $function ) { diff --git a/core/Session.php b/core/Session.php index 512eb835ef..2a0b23c104 100644 --- a/core/Session.php +++ b/core/Session.php @@ -23,7 +23,7 @@ class Piwik_Session extends Zend_Session /** * Are we using file-based session store? * - * @return bool True if file-based; false otherwise + * @return bool True if file-based; false otherwise */ public static function isFileBasedSessions() { @@ -35,7 +35,7 @@ class Piwik_Session extends Zend_Session /** * Start the session * - * @param array|bool $options An array of configuration options; the auto-start (bool) setting is ignored + * @param array|bool $options An array of configuration options; the auto-start (bool) setting is ignored * @return void */ public static function start($options = false) diff --git a/core/Session/Namespace.php b/core/Session/Namespace.php index 2393508048..c01b976a97 100644 --- a/core/Session/Namespace.php +++ b/core/Session/Namespace.php @@ -18,6 +18,10 @@ */ class Piwik_Session_Namespace extends Zend_Session_Namespace { + /** + * @param string $namespace + * @param bool $singleInstance + */ public function __construct($namespace = 'Default', $singleInstance = false) { if(Piwik_Common::isPhpCliMode()) diff --git a/core/Session/SaveHandler/DbTable.php b/core/Session/SaveHandler/DbTable.php index c891f915f5..e3e32ca890 100644 --- a/core/Session/SaveHandler/DbTable.php +++ b/core/Session/SaveHandler/DbTable.php @@ -21,6 +21,9 @@ class Piwik_Session_SaveHandler_DbTable implements Zend_Session_SaveHandler_Inte protected $config; protected $maxLifetime; + /** + * @param array $config + */ function __construct($config) { $this->config = $config; @@ -40,8 +43,8 @@ class Piwik_Session_SaveHandler_DbTable implements Zend_Session_SaveHandler_Inte /** * Open Session - retrieve resources * - * @param string $save_path - * @param string $name + * @param string $save_path + * @param string $name * @return boolean */ public function open($save_path, $name) @@ -64,7 +67,7 @@ class Piwik_Session_SaveHandler_DbTable implements Zend_Session_SaveHandler_Inte /** * Read session data * - * @param string $id + * @param string $id * @return string */ public function read($id) @@ -83,8 +86,8 @@ class Piwik_Session_SaveHandler_DbTable implements Zend_Session_SaveHandler_Inte /** * Write Session - commit data to resource * - * @param string $id - * @param mixed $data + * @param string $id + * @param mixed $data * @return boolean */ public function write($id, $data) @@ -109,7 +112,7 @@ class Piwik_Session_SaveHandler_DbTable implements Zend_Session_SaveHandler_Inte * Destroy Session - remove data from resource for * given session id * - * @param string $id + * @param string $id * @return boolean */ public function destroy($id) @@ -126,7 +129,7 @@ class Piwik_Session_SaveHandler_DbTable implements Zend_Session_SaveHandler_Inte * Garbage Collection - remove old session data older * than $maxlifetime (in seconds) * - * @param int $maxlifetime + * @param int $maxlifetime timestamp in seconds * @return true */ public function gc($maxlifetime) diff --git a/core/Site.php b/core/Site.php index 4178d1471b..30fb42bf02 100644 --- a/core/Site.php +++ b/core/Site.php @@ -16,10 +16,19 @@ */ class Piwik_Site { + /** + * @var int|null + */ protected $id = null; - + + /** + * @var array + */ public static $infoSites = array(); + /** + * @param int $idsite + */ function __construct($idsite) { $this->id = (int)$idsite; @@ -33,7 +42,7 @@ class Piwik_Site * Sets the cached Site data with an array that associates site IDs with * individual site data. * - * @param array $sites The array of sites data. Indexed by site ID. + * @param array $sites The array of sites data. Indexed by site ID. */ public static function setSites($sites) { @@ -43,7 +52,7 @@ class Piwik_Site /** * Sets the cached Site data with a non-associated array of site data. * - * @param array $sites The array of sites data. + * @param array $sites The array of sites data. */ public static function setSitesFromArray($sites) { @@ -54,7 +63,10 @@ class Piwik_Site } self::setSites($sitesById); } - + + /** + * @return string + */ function __toString() { return "site id=".$this->getId().", @@ -65,22 +77,43 @@ class Piwik_Site currency = ".$this->getCurrency().", creation date = ".$this->getCreationDate(); } - + + /** + * Returns the name of the site + * + * @return string + */ function getName() { return $this->get('name'); } - + + /** + * Returns the main url of the site + * + * @return string + */ function getMainUrl() { return $this->get('main_url'); } - + + /** + * Returns the id of the site + * + * @return int + */ function getId() { return $this->id; } - + + /** + * Returns a site property + * @param string $name property to return + * @return mixed + * @throws Exception + */ protected function get( $name) { if(!isset(self::$infoSites[$this->id][$name])) @@ -90,37 +123,70 @@ class Piwik_Site return self::$infoSites[$this->id][$name]; } + /** + * Returns the creation date of the site + * + * @return Piwik_Date + */ function getCreationDate() { $date = $this->get('ts_created'); return Piwik_Date::factory($date); } + /** + * Returns the timezone of the size + * + * @return string + */ function getTimezone() { return $this->get('timezone'); } - + + /** + * Returns the currency of the site + * + * @return string + */ function getCurrency() { return $this->get('currency'); } - + + /** + * Returns the excluded ips of the site + * + * @return string + */ function getExcludedIps() { return $this->get('excluded_ips'); } + /** + * Returns the excluded query parameters of the site + * + * @return string + */ function getExcludedQueryParameters() { return $this->get('excluded_parameters'); } + + /** + * Returns whether ecommerce id enabled for the site + * + * @return bool + */ function isEcommerceEnabled() { return $this->get('ecommerce') == 1; } /** + * Checks the given string for valid site ids and returns them as an array + * * @param string $string comma separated idSite list * @return array of valid integer */ @@ -142,7 +208,10 @@ class Piwik_Site } return $validIds; } - + + /** + * Clears the site cache + */ static public function clearCache() { self::$infoSites = array(); @@ -152,9 +221,9 @@ class Piwik_Site * Utility function. Returns the value of the specified field for the * site with the specified ID. * - * @param int|string $idsite The ID of the site whose data is being - * accessed. - * @param string $field The name of the field to get. + * @param int|string $idsite The ID of the site whose data is being + * accessed. + * @param string $field The name of the field to get. * @return mixed */ static protected function getFor($idsite, $field) @@ -172,7 +241,7 @@ class Piwik_Site /** * Returns the name of the site with the specified ID. * - * @param int $idsite The site ID. + * @param int $idsite The site ID. * @return string */ static public function getNameFor($idsite) @@ -183,7 +252,7 @@ class Piwik_Site /** * Returns the timezone of the site with the specified ID. * - * @param int $idsite The site ID. + * @param int $idsite The site ID. * @return string */ static public function getTimezoneFor($idsite) @@ -194,7 +263,7 @@ class Piwik_Site /** * Returns the creation date of the site with the specified ID. * - * @param int $idsite The site ID. + * @param int $idsite The site ID. * @return string */ static public function getCreationDateFor($idsite) @@ -205,7 +274,7 @@ class Piwik_Site /** * Returns the url for the site with the specified ID. * - * @param int $idsite The site ID. + * @param int $idsite The site ID. * @return string */ static public function getMainUrlFor($idsite) @@ -216,7 +285,7 @@ class Piwik_Site /** * Returns whether the site with the specified ID is ecommerce enabled * - * @param int $idsite The site ID. + * @param int $idsite The site ID. * @return string */ static public function isEcommerceEnabledFor($idsite) @@ -227,7 +296,7 @@ class Piwik_Site /** * Returns the currency of the site with the specified ID. * - * @param int $idsite The site ID. + * @param int $idsite The site ID. * @return string */ static public function getCurrencyFor($idsite) @@ -238,7 +307,7 @@ class Piwik_Site /** * Returns the excluded IP addresses of the site with the specified ID. * - * @param int $idsite The site ID. + * @param int $idsite The site ID. * @return string */ static public function getExcludedIpsFor($idsite) @@ -247,10 +316,9 @@ class Piwik_Site } /** - * Returns the excluded query parameters for the site with the specified - * ID. + * Returns the excluded query parameters for the site with the specified ID. * - * @param int $idsite The site ID. + * @param int $idsite The site ID. * @return string */ static public function getExcludedQueryParametersFor($idsite) diff --git a/core/Tracker/Db/Mysqli.php b/core/Tracker/Db/Mysqli.php index 05626f0a76..e2724617af 100644 --- a/core/Tracker/Db/Mysqli.php +++ b/core/Tracker/Db/Mysqli.php @@ -29,8 +29,9 @@ class Piwik_Tracker_Db_Mysqli extends Piwik_Tracker_Db /** * Builds the DB object - * @param array $dbInfo - * @param string $driverName + * + * @param array $dbInfo + * @param string $driverName */ public function __construct( $dbInfo, $driverName = 'mysql') { @@ -58,6 +59,9 @@ class Piwik_Tracker_Db_Mysqli extends Piwik_Tracker_Db $this->charset = isset($dbInfo['charset']) ? $dbInfo['charset'] : null; } + /** + * Destructor + */ public function __destruct() { $this->connection = null; @@ -66,7 +70,7 @@ class Piwik_Tracker_Db_Mysqli extends Piwik_Tracker_Db /** * Connects to the DB * - * @throws Exception|Piwik_Tracker_Db_Exception if there was an error connecting the DB + * @throws Exception|Piwik_Tracker_Db_Exception if there was an error connecting the DB */ public function connect() { @@ -105,11 +109,12 @@ class Piwik_Tracker_Db_Mysqli extends Piwik_Tracker_Db /** * Returns an array containing all the rows of a query result, using optional bound parameters. - * - * @param string $query Query - * @param array $parameters Parameters to bind + * + * @see query() + * + * @param string $query Query + * @param array $parameters Parameters to bind * @return array - * @see also query() * @throws Exception|Piwik_Tracker_Db_Exception if an exception occured */ public function fetchAll( $query, $parameters = array() ) @@ -146,12 +151,12 @@ class Piwik_Tracker_Db_Mysqli extends Piwik_Tracker_Db /** * Returns the first row of a query result, using optional bound parameters. - * - * @param string Query - * @param array Parameters to bind - * @see also query() - * - * @throws Exception if an exception occured + * + * @see query() + * + * @param string $query Query + * @param array $parameters Parameters to bind + * @throws Piwik_Tracker_Db_Exception if an exception occured */ public function fetch( $query, $parameters = array() ) { @@ -184,11 +189,11 @@ class Piwik_Tracker_Db_Mysqli extends Piwik_Tracker_Db /** * Executes a query, using optional bound parameters. * - * @param string Query - * @param array|string Parameters to bind array('idsite'=> 1) + * @param string $query Query + * @param array|string $parameters Parameters to bind array('idsite'=> 1) * - * @return bool|resource false if failed - * @throws Exception if an exception occured + * @return bool|resource false if failed + * @throws Piwik_Tracker_Db_Exception if an exception occured */ public function query($query, $parameters = array()) { @@ -236,8 +241,8 @@ class Piwik_Tracker_Db_Mysqli extends Piwik_Tracker_Db * Input is a prepared SQL statement and parameters * Returns the SQL statement * - * @param string $query - * @param array $parameters + * @param string $query + * @param array $parameters * @return string */ private function prepare($query, $parameters) { @@ -263,8 +268,8 @@ class Piwik_Tracker_Db_Mysqli extends Piwik_Tracker_Db /** * Test error number * - * @param Exception $e - * @param string $errno + * @param Exception $e + * @param string $errno * @return bool */ public function isErrNo($e, $errno) @@ -275,7 +280,7 @@ class Piwik_Tracker_Db_Mysqli extends Piwik_Tracker_Db /** * Return number of affected rows in last query * - * @param mixed $queryResult Result from query() + * @param mixed $queryResult Result from query() * @return int */ public function rowCount($queryResult) diff --git a/core/Tracker/Db/Pdo/Mysql.php b/core/Tracker/Db/Pdo/Mysql.php index 72752436f6..42e213d640 100644 --- a/core/Tracker/Db/Pdo/Mysql.php +++ b/core/Tracker/Db/Pdo/Mysql.php @@ -147,11 +147,10 @@ class Piwik_Tracker_Db_Pdo_Mysql extends Piwik_Tracker_Db /** * Executes a query, using optional bound parameters. * - * @param string Query - * @param array|string Parameters to bind array('idsite'=> 1) - * - * @return PDOStatement or false if failed - * @throws Exception if an exception occured + * @param string $query Query + * @param array|string $parameters Parameters to bind array('idsite'=> 1) + * @return PDOStatement|bool PDOStatement or false if failed + * @throws Piwik_Tracker_Db_Exception if an exception occured */ public function query($query, $parameters = array()) { diff --git a/core/Unzip.php b/core/Unzip.php index b97ccb177a..1031df4540 100644 --- a/core/Unzip.php +++ b/core/Unzip.php @@ -20,9 +20,9 @@ class Piwik_Unzip /** * Factory method to create an unarchiver * - * @param string $name Name of unarchiver - * @param string $filename Name of .zip archive - * @return Piwik_Unzip + * @param string $name Name of unarchiver + * @param string $filename Name of .zip archive + * @return Piwik_Unzip_Interface */ static public function factory($name, $filename) { diff --git a/core/Unzip/Interface.php b/core/Unzip/Interface.php index cd86202281..b9db2a5719 100644 --- a/core/Unzip/Interface.php +++ b/core/Unzip/Interface.php @@ -21,15 +21,15 @@ interface Piwik_Unzip_Interface /** * Constructor * - * @param string $filename Name of the .zip archive + * @param string $filename Name of the .zip archive */ - function __construct($filename); + public function __construct($filename); /** * Extract files from archive to target directory * - * @param string $pathExtracted Absolute path of target directory - * @return mixed Array of filenames if successful; or 0 if an error occurred + * @param string $pathExtracted Absolute path of target directory + * @return mixed Array of filenames if successful; or 0 if an error occurred */ public function extract($pathExtracted); diff --git a/core/Unzip/PclZip.php b/core/Unzip/PclZip.php index 925da5ba7a..e0b3f6be2b 100644 --- a/core/Unzip/PclZip.php +++ b/core/Unzip/PclZip.php @@ -23,14 +23,31 @@ require_once PIWIK_INCLUDE_PATH . '/libs/PclZip/pclzip.lib.php'; */ class Piwik_Unzip_PclZip implements Piwik_Unzip_Interface { + /** + * @var PclZip + */ private $pclzip; + /** + * @var string + */ public $filename; - function __construct($filename) { + /** + * Constructor + * + * @param string $filename Name of the .zip archive + */ + public function __construct($filename) { $this->pclzip = new PclZip($filename); $this->filename = $filename; } + /** + * Extract files from archive to target directory + * + * @param string $pathExtracted Absolute path of target directory + * @return mixed Array of filenames if successful; or 0 if an error occurred + */ public function extract($pathExtracted) { $pathExtracted = str_replace('\\', '/', $pathExtracted); $list = $this->pclzip->listContent(); @@ -63,6 +80,11 @@ class Piwik_Unzip_PclZip implements Piwik_Unzip_Interface ); } + /** + * Get error status string for the latest error + * + * @return string + */ public function errorInfo() { return $this->pclzip->errorInfo(true); } diff --git a/core/Unzip/ZipArchive.php b/core/Unzip/ZipArchive.php index 61042a56f6..bbf17ad692 100644 --- a/core/Unzip/ZipArchive.php +++ b/core/Unzip/ZipArchive.php @@ -16,12 +16,24 @@ * @package Piwik * @subpackage Piwik_Unzip */ -class Piwik_Unzip_ZipArchive implements Piwik_Unzip_Interface +class Piwik_Unzip_ZipArchive implements Piwik_Unzip_Interface { + /** + * @var ZipArchive + */ private $ziparchive; + /** + * @var string + */ public $filename; - function __construct($filename) { + /** + * Constructor + * + * @param string $filename Name of the .zip archive + * @throws Exception + */ + public function __construct($filename) { $this->filename = $filename; $this->ziparchive = new ZipArchive; if($this->ziparchive->open($filename) !== true) { @@ -29,6 +41,12 @@ class Piwik_Unzip_ZipArchive implements Piwik_Unzip_Interface } } + /** + * Extract files from archive to target directory + * + * @param string $pathExtracted Absolute path of target directory + * @return mixed Array of filenames if successful; or 0 if an error occurred + */ public function extract($pathExtracted) { if(substr_compare($pathExtracted, '/', -1)) $pathExtracted .= '/'; @@ -71,6 +89,11 @@ class Piwik_Unzip_ZipArchive implements Piwik_Unzip_Interface return $list; } + /** + * Get error status string for the latest error + * + * @return string + */ public function errorInfo() { static $statusStrings = array( ZIPARCHIVE::ER_OK => 'No error', diff --git a/core/UpdateCheck.php b/core/UpdateCheck.php index 6cff6cf202..917cff1487 100644 --- a/core/UpdateCheck.php +++ b/core/UpdateCheck.php @@ -25,7 +25,7 @@ class Piwik_UpdateCheck /** * Check for a newer version * - * @param bool $force Force check + * @param bool $force Force check */ public static function check($force = false) { @@ -65,8 +65,8 @@ class Piwik_UpdateCheck /** * Returns version number of a newer Piwik release. * - * @return string|false false if current version is the latest available, - * or the latest version number if a newest release is available + * @return string|false false if current version is the latest available, + * or the latest version number if a newest release is available */ public static function isNewestVersionAvailable() { diff --git a/core/Updates.php b/core/Updates.php index fc94032c4c..f932227ad9 100644 --- a/core/Updates.php +++ b/core/Updates.php @@ -21,12 +21,12 @@ abstract class Piwik_Updates /** * Return SQL to be executed in this update * - * @param string Schema name + * @param string $schema Schema name * @return array( - * 'ALTER .... ' => '1234', // if the query fails, it will be ignored if the error code is 1234 - * 'ALTER .... ' => false, // if an error occurs, the update will stop and fail - * // and user will have to manually run the query - * ) + * 'ALTER .... ' => '1234', // if the query fails, it will be ignored if the error code is 1234 + * 'ALTER .... ' => false, // if an error occurs, the update will stop and fail + * // and user will have to manually run the query + * ) */ static function getSql($schema = 'Myisam') { diff --git a/core/Version.php b/core/Version.php index 11b1b0acae..8e95fce284 100644 --- a/core/Version.php +++ b/core/Version.php @@ -17,5 +17,9 @@ */ final class Piwik_Version { + /** + * Current Piwik version + * @var string + */ const VERSION = '1.7.2-rc8'; } |