From 4b74c5c44d37c2269991b5a8dc185db0fc40136a Mon Sep 17 00:00:00 2001
From: Thomas Steur <thomas.steur@gmail.com>
Date: Tue, 8 Oct 2013 23:23:00 +0000
Subject: [PATCH] refs #4199 updated some event docs and removed some more
unused events
---
core/API/Request.php | 3 ++-
core/AssetManager.php | 10 +++++-----
core/Db.php | 13 ++-----------
core/FrontController.php | 17 +++++++++--------
core/Menu/Admin.php | 6 +++---
core/Menu/Main.php | 6 +++---
core/Tracker.php | 15 ++-------------
core/Tracker/Action.php | 2 +-
core/Tracker/GoalManager.php | 6 +++---
core/Tracker/Request.php | 2 +-
core/Tracker/Visit.php | 8 ++++----
core/ViewDataTable.php | 2 +-
core/ViewDataTable/Visualization.php | 4 ++--
core/WidgetsList.php | 4 ++--
plugins/API/ProcessedReport.php | 2 +-
plugins/Goals/Goals.php | 3 ++-
plugins/Installation/Installation.php | 6 ------
plugins/SegmentEditor/API.php | 2 +-
plugins/UsersManager/API.php | 4 ++--
plugins/UsersManager/Controller.php | 16 ++++++++++++++++
20 files changed, 62 insertions(+), 69 deletions(-)
diff --git a/core/API/Request.php b/core/API/Request.php
index 5cb9a7c9ac..af8687a11c 100644
--- a/core/API/Request.php
+++ b/core/API/Request.php
@@ -184,7 +184,8 @@ class Request
/**
* 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));
diff --git a/core/AssetManager.php b/core/AssetManager.php
index c75f9435a7..f199ce85fa 100644
--- a/core/AssetManager.php
+++ b/core/AssetManager.php
@@ -161,9 +161,9 @@ class AssetManager
$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 @@ class AssetManager
$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:
diff --git a/core/Db.php b/core/Db.php
index b7e0dd59c5..c6119205e5 100644
--- a/core/Db.php
+++ b/core/Db.php
@@ -63,18 +63,9 @@ class Db
$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;
}
diff --git a/core/FrontController.php b/core/FrontController.php
index 155cac103f..6c9b96be6b 100644
--- a/core/FrontController.php
+++ b/core/FrontController.php
@@ -125,8 +125,8 @@ class FrontController
/**
* 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)`
*/
@@ -134,7 +134,7 @@ class FrontController
/**
* 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 @@ class FrontController
/**
* 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 @@ class FrontController
* 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 {
diff --git a/core/Menu/Admin.php b/core/Menu/Admin.php
index 7e74b20468..d32335d4d4 100644
--- a/core/Menu/Admin.php
+++ b/core/Menu/Admin.php
@@ -41,9 +41,9 @@ class Admin extends MenuAbstract
/**
* 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:
* ```
diff --git a/core/Menu/Main.php b/core/Menu/Main.php
index 595cf82f5f..1511a3f9fb 100644
--- a/core/Menu/Main.php
+++ b/core/Menu/Main.php
@@ -61,9 +61,9 @@ class Main extends MenuAbstract
/**
* 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:
* ```
diff --git a/core/Tracker.php b/core/Tracker.php
index b541129ae3..a9a3855695 100644
--- a/core/Tracker.php
+++ b/core/Tracker.php
@@ -576,18 +576,7 @@ class Tracker
}
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 @@ class Tracker
* 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();
diff --git a/core/Tracker/Action.php b/core/Tracker/Action.php
index 1555b95f8f..c869cf8a53 100644
--- a/core/Tracker/Action.php
+++ b/core/Tracker/Action.php
@@ -641,7 +641,7 @@ class Action implements ActionInterface
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));
diff --git a/core/Tracker/GoalManager.php b/core/Tracker/GoalManager.php
index be7255d199..7c8b3bbc81 100644
--- a/core/Tracker/GoalManager.php
+++ b/core/Tracker/GoalManager.php
@@ -406,7 +406,7 @@ class GoalManager
}
/**
- * 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 @@ class GoalManager
$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));
}
diff --git a/core/Tracker/Request.php b/core/Tracker/Request.php
index 795f9a04f3..7ae021fb0b 100644
--- a/core/Tracker/Request.php
+++ b/core/Tracker/Request.php
@@ -294,7 +294,7 @@ class Request
/**
* 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));
diff --git a/core/Tracker/Visit.php b/core/Tracker/Visit.php
index df0f9f86b5..ca55b00e75 100644
--- a/core/Tracker/Visit.php
+++ b/core/Tracker/Visit.php
@@ -306,7 +306,7 @@ class Visit implements VisitInterface
$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 @@ class Visit implements VisitInterface
}
/**
- * 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 @@ class Visit implements VisitInterface
);
/**
- * 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.
*/
diff --git a/core/ViewDataTable.php b/core/ViewDataTable.php
index c37b067ba2..d93d95dbd3 100644
--- a/core/ViewDataTable.php
+++ b/core/ViewDataTable.php
@@ -427,7 +427,7 @@ class ViewDataTable
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:
diff --git a/core/ViewDataTable/Visualization.php b/core/ViewDataTable/Visualization.php
index a25bf52c9c..98111be77a 100644
--- a/core/ViewDataTable/Visualization.php
+++ b/core/ViewDataTable/Visualization.php
@@ -151,8 +151,8 @@ abstract class Visualization extends View
$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));
diff --git a/core/WidgetsList.php b/core/WidgetsList.php
index 6e219acabf..3696cd02f2 100644
--- a/core/WidgetsList.php
+++ b/core/WidgetsList.php
@@ -58,8 +58,8 @@ class WidgetsList
/**
* 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:
* ```
diff --git a/plugins/API/ProcessedReport.php b/plugins/API/ProcessedReport.php
index 204ef8ff7d..eeea9bb4ca 100644
--- a/plugins/API/ProcessedReport.php
+++ b/plugins/API/ProcessedReport.php
@@ -109,7 +109,7 @@ class ProcessedReport
}
/**
- * 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));
diff --git a/plugins/Goals/Goals.php b/plugins/Goals/Goals.php
index d6f7148b71..222516ec90 100644
--- a/plugins/Goals/Goals.php
+++ b/plugins/Goals/Goals.php
@@ -339,6 +339,8 @@ class Goals extends \Piwik\Plugin
unset($goalMetrics['nb_visits_converted']);
+ $reportsWithGoals = array();
+
/*
* Add the metricsGoal and processedMetricsGoal entry
* to all reports that have Goal segmentation
@@ -347,7 +349,6 @@ class Goals extends \Piwik\Plugin
* 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
diff --git a/plugins/Installation/Installation.php b/plugins/Installation/Installation.php
index 77a3e33471..e76484c777 100644
--- a/plugins/Installation/Installation.php
+++ b/plugins/Installation/Installation.php
@@ -59,12 +59,6 @@ class Installation extends \Piwik\Plugin
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'));
diff --git a/plugins/SegmentEditor/API.php b/plugins/SegmentEditor/API.php
index 1fb8ad7afd..f98d93e72f 100644
--- a/plugins/SegmentEditor/API.php
+++ b/plugins/SegmentEditor/API.php
@@ -311,7 +311,7 @@ class API
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));
diff --git a/plugins/UsersManager/API.php b/plugins/UsersManager/API.php
index f68ff3d512..98ec5a97df 100644
--- a/plugins/UsersManager/API.php
+++ b/plugins/UsersManager/API.php
@@ -460,8 +460,8 @@ class API
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));
}
diff --git a/plugins/UsersManager/Controller.php b/plugins/UsersManager/Controller.php
index 1ad2051d7d..3241b7e30f 100644
--- a/plugins/UsersManager/Controller.php
+++ b/plugins/UsersManager/Controller.php
@@ -322,6 +322,22 @@ class Controller extends Admin
'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));
}
--
GitLab