refs #4199 updated some event docs and removed some more unused events

core/API/Request.php

@@ -184,7 +184,8 @@ static public function reloadAuthUsingTokenAuth($request = null)
 
             /**
              * This event will be triggered if the token_auth is found in the $request parameter. In this case the
-             * current session will be authenticated using this token_auth. It will overwrite the previous Auth object.
+             * current session will be authenticated using this token_auth. It will overwrite the previous `Auth`
+             * object.
              * @matt
              */
             Piwik_PostEvent('API.Request.authenticate', array($token_auth));

core/AssetManager.php

@@ -161,9 +161,9 @@ private static function prepareMergedCssFile()
         $mergedContent = $less->compile($mergedContent);
 
         /**
-         * This event is triggered after the less stylesheets are compiled to CSS, minified and merged but before the
-         * generated CSS is written to disk. It can be used to change the generated stylesheets to your needs,
-         * like replacing image paths or adding further custom stylesheets.
+         * This event is triggered after the less stylesheets are compiled to CSS and after the CSS is minified and
+         * merged into one file but before the generated CSS is written to disk. It can be used to change the modify the
+         * stylesheets to your needs, like replacing image paths or adding further custom stylesheets.
          */
         Piwik_PostEvent('AssetManager.filterMergedStylesheets', array(&$mergedContent));
 
@@ -286,9 +286,9 @@ private static function getStylesheetFiles()
         $stylesheets = array();
 
         /**
-         * This event is triggered to gather a list of all stylesheets (CSS and Less). Use this event to add your own
+         * This event is triggered to gather a list of all stylesheets (CSS and LESS). Use this event to add your own
          * stylesheets. Note: In case you are in development you may enable the config setting `disable_merged_assets`.
-         * Otherwise your custom stylesheets won't be loaded. It is best practice to place stylesheet files within a
+         * Otherwise your custom stylesheets won't be loaded. It is best practice to place stylesheets within a
          * `stylesheets` folder.
          *
          * Example:

core/Db.php

@@ -63,18 +63,9 @@ public static function createDatabaseObject($dbInfos = null)
 
         $dbInfos['profiler'] = $config->Debug['enable_sql_profiler'];
 
-        $db = null;
+        $adapter = $dbInfos['adapter'];
+        $db      = @Adapter::factory($adapter, $dbInfos);
 
-        /**
-         * This event is triggered after the database config is loaded but immediately before a connection to the
-         * database is established. Use this event to create your own database handler instead of the default Piwik
-         * DB handler.
-         */
-        Piwik_PostEvent('Reporting.createDatabase', array(&$db));
-        if (is_null($db)) {
-            $adapter = $dbInfos['adapter'];
-            $db = @Adapter::factory($adapter, $dbInfos);
-        }
         self::$connection = $db;
     }
 

core/FrontController.php

@@ -125,16 +125,16 @@ public function dispatch($module = null, $action = null, $parameters = null)
 
         /**
          * Generic hook that plugins can use to modify any input to the function, or even change the plugin being
-         * called. You could also use this to build an enhanced permission system. The event is triggered before any
-         * controller is called.
+         * called. You could also use this to build an enhanced permission system. The event is triggered before every
+         * call to a controller method.
          *
          * The `$params` array contains the following properties: `array($module, $action, $parameters, $controller)`
          */
         Piwik_PostEvent('Request.dispatch', $params);
 
         /**
          * This event is similar to the `Request.dispatch` hook. It distinguishes the possibility to subscribe only to a
-         * specific controller call instead of all controller calls. You can use it for example to modify any input
+         * specific controller method instead of all controller methods. You can use it for example to modify any input
          * parameters or execute any other logic before the actual controller is called.
          */
         Piwik_PostEvent(sprintf('Controller.%s.%s', $module, $action), array($parameters));
@@ -144,15 +144,15 @@ public function dispatch($module = null, $action = null, $parameters = null)
 
             /**
              * This event is similar to the `Request.dispatch.end` hook. It distinguishes the possibility to subscribe
-             * only to the end of a specific controller call instead of all controller calls. You can use it for example
-             * to modify the response of a single controller.
+             * only to the end of a specific controller method instead of all controller methods. You can use it for
+             * example to modify the response of a single controller method.
              */
             Piwik_PostEvent(sprintf('Controller.%s.%s.end', $module, $action), array(&$result, $parameters));
 
             /**
-             * Generic hook that plugins can use to modify any output of any controller. The event is triggered after
-             * any controller is executed but before the result is send to the user. The parameters originally
-             * passed to the controller are available as well.
+             * Generic hook that plugins can use to modify any output of any controller method. The event is triggered
+             * after a controller method is executed but before the result is send to the user. The parameters
+             * originally passed to the method are available as well.
              */
             Piwik_PostEvent('Request.dispatch.end', array(&$result, $parameters));
 
@@ -343,6 +343,7 @@ public function init()
              * This event is triggered shortly before the user is authenticated. Use it to create your own
              * authentication object instead of the Piwik authentication. Make sure to implement the `Piwik\Auth`
              * interface in case you want to define your own authentication.
+             * @matt here we have a problem if multiple plugins listen to this event?
              */
             Piwik_PostEvent('Request.initAuthenticationObject');
             try {

core/Menu/Admin.php

@@ -41,9 +41,9 @@ public function get()
 
             /**
              * This event is triggered to collect all available admin menu items. Subscribe to this event if you want
-             * to add one or more items to the Piwik admin menu. It's fairly easy. Just define the name of your menu
-             * item as well as a controller and an action that should be executed once a user selects your menu item.
-             * It is also possible to display the item only for users having a specific role.
+             * to add one or more items to the Piwik admin menu. Just define the name of your menu item as well as a
+             * controller and an action that should be executed once a user selects your menu item. It is also possible
+             * to display the item only for users having a specific role.
              *
              * Example:
              * ```

core/Menu/Main.php

@@ -61,9 +61,9 @@ public function get()
 
             /**
              * This event is triggered to collect all available reporting menu items. Subscribe to this event if you
-             * want to add one or more items to the Piwik reporting menu. It's fairly easy. Just define the name of your
-             * menu item as well as a controller and an action that should be executed once a user selects your menu
-             * item. It is also possible to display the item only for users having a specific role.
+             * want to add one or more items to the Piwik reporting menu. Just define the name of your menu item as
+             * well as a controller and an action that should be executed once a user selects your menu item. It is
+             * also possible to display the item only for users having a specific role.
              *
              * Example:
              * ```

core/Tracker.php

@@ -576,18 +576,7 @@ public static function connectDatabaseIfNotConnected()
         }
 
         try {
-            $db = null;
-
-            /**
-             * This event is triggered after the database config is loaded but immediately before a connection to the
-             * database is established. Use this event to create your own database handler instead of the default Piwik
-             * DB handler.
-             */
-            Piwik_PostEvent('Tracker.createDatabase', array(&$db));
-            if (is_null($db)) {
-                $db = self::connectPiwikTrackerDb();
-            }
-            self::$db = $db;
+            self::$db = self::connectPiwikTrackerDb();
         } catch (Exception $e) {
             throw new DbException($e->getMessage(), $e->getCode());
         }
@@ -625,7 +614,7 @@ protected function getNewVisitObject()
          * usage of your own or your extended visit object but make sure to implement the
          * `Piwik\Tracker\VisitInterface`.
          */
-        Piwik_PostEvent('Tracker.getNewVisitObject', array(&$visit));
+        Piwik_PostEvent('Tracker.makeNewVisitObject', array(&$visit));
 
         if (is_null($visit)) {
             $visit = new Visit();

core/Tracker/Action.php

@@ -641,7 +641,7 @@ public function record($idVisit, $visitorIdCookie, $idReferrerActionUrl, $idRefe
         Common::printDebug($insertWithoutNulls);
 
         /**
-         * This hook is called after saving (and updating) visitor information. You can use for instance to sync the
+         * This hook is called after saving (and updating) visitor information. You can use it for instance to sync the
          * recorded action with third party systems.
          */
         Piwik_PostEvent('Tracker.recordAction', array($trackerAction = $this, $info));

core/Tracker/GoalManager.php

@@ -406,7 +406,7 @@ protected function recordEcommerceGoal($goal, $visitorInformation)
         }
 
         /**
-         * This hook is called after recording an ecommerce goal. You can use for instance to sync the recorded goal
+         * This hook is called after recording an ecommerce goal. You can use it for instance to sync the recorded goal
          * with third party systems. `$goal` contains all available information like `items` and `revenue`.
          */
         Piwik_PostEvent('Tracker.recordEcommerceGoal', array($goal));
@@ -771,8 +771,8 @@ protected function recordStandardGoals($goal, $action, $visitorInformation)
             $this->recordGoal($newGoal);
 
             /**
-             * This hook is called after recording a standard goal. You can use for instance to sync the recorded goal
-             * with third party systems. `$goal` contains all available information like `url` and `revenue`.
+             * This hook is called after recording a standard goal. You can use it for instance to sync the recorded
+             * goal with third party systems. `$goal` contains all available information like `url` and `revenue`.
              */
             Piwik_PostEvent('Tracker.recordStandardGoals', array($newGoal));
         }

core/Tracker/Request.php

@@ -294,7 +294,7 @@ public function getIdSite()
 
         /**
          * This event allows a plugin to set/change the idsite in the tracking request. Note: A modified idSite has to
-         * be higher than 0, otherwise an exception will be triggered. By default the idSite is specified on the URL
+         * be higher than `0`, otherwise an exception will be triggered. By default the idSite is specified on the URL
          * parameter `idsite`.
          */
         Piwik_PostEvent('Tracker.setSiteId', array(&$idSite, $this->params));

core/Tracker/Visit.php

@@ -306,7 +306,7 @@ protected function handleKnownVisit($idActionUrl, $idActionName, $actionType, $v
         $valuesToUpdate = array_merge($valuesToUpdate, $this->visitorCustomVariables);
 
         /**
-         * This event is triggered before a known visitor is updated. Use it to change any visitor information before
+         * This event is triggered before saving a known visitor. Use it to change any visitor information before
          * the visitor is saved.
          */
         Piwik_PostEvent('Tracker.knownVisitorUpdate', array(&$valuesToUpdate));
@@ -351,8 +351,8 @@ protected function handleKnownVisit($idActionUrl, $idActionName, $actionType, $v
         }
 
         /**
-         * After a known visitor is updated by Piwik, this event is called. Useful for plugins that want to register
-         * information about a returning visitor, or filter the existing information.
+         * After a known visitor is saved and updated by Piwik, this event is called. Useful for plugins that want to
+         * register information about a returning visitor, or filter the existing information.
          */
         Piwik_PostEvent('Tracker.knownVisitorInformation', array(&$this->visitorInfo));
     }
@@ -472,7 +472,7 @@ protected function handleNewVisit($idActionUrl, $idActionName, $actionType, $vis
         );
 
         /**
-         * Before a new visitor is updated by Piwik, this event is called. Useful for plugins that want to register
+         * Before a new visitor is saved by Piwik, this event is called. Useful for plugins that want to register
          * new information about a visitor, or filter the existing information. `$extraInfo` contains the UserAgent.
          * You can for instance change the user's location country depending on the User Agent.
          */

core/ViewDataTable.php

@@ -427,7 +427,7 @@ private static function getAllReportDisplayProperties()
             self::$reportPropertiesCache = array();
             /**
              * This event is triggered to gather the report display properties for each available report. If you define
-             * your own report, you mant to subscribe to this event to define how your report shall be displayed in the
+             * your own report, you want to subscribe to this event to define how your report shall be displayed in the
              * Piwik UI.
              *
              * Example:

core/ViewDataTable/Visualization.php

@@ -151,8 +151,8 @@ public static function getAvailableVisualizations()
         $visualizations = array();
 
         /**
-         * This event is used to gather all available DataTable visualizations. Callbacks
-         * should add visualization class names to the incoming array.
+         * This event is used to gather all available DataTable visualizations. Callbacks should add visualization
+         * class names to the incoming array.
          */
         Piwik_PostEvent(self::GET_AVAILABLE_EVENT, array(&$visualizations));
 

core/WidgetsList.php

@@ -58,8 +58,8 @@ private static function addWidgets()
 
             /**
              * This event is triggered to collect all available widgets. Subscribe to this event if you want to create
-             * one or more custom widgets. It's fairly easy. Just define the name of your widgets as well as a
-             * controller and an action that should be executed once your widget is requested.
+             * one or more custom widgets. Just define the name of your widgets as well as a controller and an action
+             * that should be executed once your widget is requested.
              *
              * Example:
              * ```

plugins/API/ProcessedReport.php

@@ -109,7 +109,7 @@ public function getReportMetadata($idSites, $period = false, $date = false, $hid
         }
 
         /**
-         * This event is triggered to after all available reports are collected. Plugins can add custom metrics to
+         * This event is triggered after all available reports are collected. Plugins can add custom metrics to
          * other reports or remove reports from the list of all available reports.
          */
         Piwik_PostEvent('API.getReportMetadata.end', array(&$availableReports, $parameters));

plugins/Goals/Goals.php

@@ -339,6 +339,8 @@ public function getReportMetadata(&$reports, $info)
 
         unset($goalMetrics['nb_visits_converted']);
 
+        $reportsWithGoals = array();
+
         /*
          * Add the metricsGoal and processedMetricsGoal entry
          * to all reports that have Goal segmentation
@@ -347,7 +349,6 @@ public function getReportMetadata(&$reports, $info)
          * generated documentation. Maybe we can create a private/protected function to trigger this event to have it
          * defined only once?
          */
-        $reportsWithGoals = array();
         Piwik_PostEvent('Goals.getReportsWithGoalMetrics', array(&$reportsWithGoals));
         foreach ($reportsWithGoals as $reportWithGoals) {
             // Select this report from the API metadata array

plugins/Installation/Installation.php

@@ -59,12 +59,6 @@ public function dispatch($exception = null)
 
         Translate::getInstance()->loadCoreTranslation();
 
-        /**
-         * This event is triggered when the installation will be started. You can use this event to modify the
-         * installation process to your needs (adding/removing steps, removing steps, etc.).
-         */
-        Piwik_PostEvent('Installation.startInstallation', array($installation = $this));
-
         $step = Common::getRequestVar('action', 'welcome', 'string');
         $controller = $this->getInstallationController();
         $isActionWhiteListed = in_array($step, array('saveLanguage', 'getBaseCss'));

plugins/SegmentEditor/API.php

@@ -311,7 +311,7 @@ public function getAll($idSite = false, $returnOnlyAutoArchived = false)
     private function sendSegmentDeactivationEvent($idSegment)
     {
         /**
-         * This event is triggered then a segment is deleted or made invisible. It allows plugins to throw an exception
+         * This event is triggered when a segment is deleted or made invisible. It allows plugins to throw an exception
          * or to propagate the action.
          */
         Piwik_PostEvent(self::DEACTIVATE_SEGMENT_EVENT, array(&$idSegment));

plugins/UsersManager/API.php

@@ -460,8 +460,8 @@ public function updateUser($userLogin, $password = false, $email = false, $alias
         Cache::deleteTrackerCache();
 
         /**
-         * This event is triggered after an existing user has updated its information and after the data has been saved.
-         * `$userLogin` contains the updated user information like login name, alias and email.
+         * This event is triggered after an existing user has been updated. `$userLogin` contains the updated user
+         * information like login name, alias and email.
          */
         Piwik_PostEvent('UsersManager.updateUser.end', array($userLogin));
     }

plugins/UsersManager/Controller.php

@@ -322,6 +322,22 @@ public function recordUserSettings()
                     'md5Password' => md5($newPassword),
                     'rememberMe'  => false,
                 );
+
+                /**
+                 * This event is triggered to initialize a user session. You can use this event to authenticate user against
+                 * third party systems.
+                 *
+                 * Example:
+                 * ```
+                 * public function initSession($info)
+                 * {
+                 *     $login = $info['login'];
+                 *     $md5Password = $info['md5Password'];
+                 *     $rememberMe = $info['rememberMe'];
+                 * }
+                 * ```
+                 * @matt this event is also triggered twice.
+                 */
                 Piwik_PostEvent('Login.initSession', array($info));
             }