refs #4199 documented some events

core/.htaccess

@@ -0,0 +1,13 @@
+<Files "*">
+<IfModule mod_access.c>
+Deny from all
+</IfModule>
+<IfModule !mod_access_compat>
+<IfModule mod_authz_host.c>
+Deny from all
+</IfModule>
+</IfModule>
+<IfModule mod_access_compat>
+Deny from all
+</IfModule>
+</Files>

core/AssetManager.php

@@ -160,6 +160,11 @@ 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.
+         */
         Piwik_PostEvent('AssetManager.filterMergedStylesheets', array(&$mergedContent));
 
         $mergedContent =
@@ -279,6 +284,22 @@ private static function getIndividualCssIncludes()
     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
+         * 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
+         * `stylesheets` folder.
+         *
+         * Example:
+         * ```
+         * public function getStylesheetFiles(&$stylesheets)
+         * {
+         *     $stylesheets[] = "plugins/MyPlugin/stylesheets/myfile.less";
+         *     $stylesheets[] = "plugins/MyPlugin/stylesheets/myfile.css";
+         * }
+         * ```
+         */
         Piwik_PostEvent(self::STYLESHEET_IMPORT_EVENT, array(&$stylesheets));
 
         $stylesheets = self::sortCssFiles($stylesheets);
@@ -356,6 +377,11 @@ private static function generateMergedJsFile()
         }
         $mergedContent = str_replace("\n", "\r\n", $mergedContent);
 
+        /**
+         * This event is triggered after the JavaScript files are minified and merged to a single file but before the
+         * generated JS file is written to disk. It can be used to change the generated JavaScript to your needs,
+         * like adding further scripts or storing the generated file somewhere else.
+         */
         Piwik_PostEvent('AssetManager.filterMergedJavaScripts', array(&$mergedContent));
 
         self::writeAssetToFile($mergedContent, self::MERGED_JS_FILE);
@@ -386,6 +412,22 @@ private static function getIndividualJsIncludes()
     private static function getJsFiles()
     {
         $jsFiles = array();
+
+        /**
+         * This event is triggered to gather a list of all JavaScript files. Use this event to add your own JavaScript
+         * files. Note: In case you are in development you may enable the config setting `disable_merged_assets`.
+         * Otherwise your custom JavaScript won't be loaded. It is best practice to place all your JavaScript files
+         * within a `javascripts` folder.
+         *
+         * Example:
+         * ```
+         * public function getJsFiles(&jsFiles)
+         * {
+         *     jsFiles[] = "plugins/MyPlugin/javascripts/myfile.js";
+         *     jsFiles[] = "plugins/MyPlugin/javascripts/anotherone.js";
+         * }
+         * ```
+         */
         Piwik_PostEvent(self::JAVASCRIPT_IMPORT_EVENT, array(&$jsFiles));
         $jsFiles = self::sortJsFiles($jsFiles);
         return $jsFiles;

core/Db.php

@@ -55,11 +55,22 @@ public static function createDatabaseObject($dbInfos = null)
             $dbInfos = $config->database;
         }
 
+        /**
+         * This event is triggered before a connection to the database is established. Use it to dynamically change the
+         * datatabase settings defined in the config. The reporting database config is used in case someone accesses
+         * the Piwik UI.
+         */
         Piwik_PostEvent('Reporting.getDatabaseConfig', array(&$dbInfos));
 
         $dbInfos['profiler'] = $config->Debug['enable_sql_profiler'];
 
         $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('Reporting.createDatabase', array(&$db));
         if (is_null($db)) {
             $adapter = $dbInfos['adapter'];

core/FrontController.php

@@ -123,20 +123,49 @@ public function dispatch($module = null, $action = null, $parameters = null)
         // list($module, $action, $parameters, $controller)
         $params = $this->prepareDispatch($module, $action, $parameters);
 
-        // Generic hook that plugins can use to modify any input to the function,
-        // or even change the plugin being called
+        /**
+         * 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.
+         *
+         * 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
+         * parameters or execute any other logic before the actual controller is called.
+         */
         Piwik_PostEvent(sprintf('Controller.%s.%s', $module, $action), array($parameters));
 
         try {
             $result = call_user_func_array(array($params[3], $params[1]), $params[2]);
+
+            /**
+             * 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.
+             */
             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.
+             */
             Piwik_PostEvent('Request.dispatch.end', array(&$result, $parameters));
 
             return $result;
 
-        } catch (NoAccessException $e) {
-            Piwik_PostEvent('User.isNotAuthorized', array($e), $pending = true);
+        } catch (NoAccessException $exception) {
+
+            /**
+             * This event is triggered in case the user wants to access anything in the Piwik UI but has not the
+             * required permissions to do this. You can subscribe to this event to display a custom error message or
+             * to display a custom login form in such a case.
+             */
+            Piwik_PostEvent('User.isNotAuthorized', array($exception), $pending = true);
         } catch (Exception $e) {
             $debugTrace = $e->getTraceAsString();
             $message = Common::sanitizeInputValue($e->getMessage());
@@ -209,9 +238,15 @@ static public function createConfigObject()
         $exceptionToThrow = false;
         try {
             Config::getInstance();
-        } catch (Exception $e) {
-            Piwik_PostEvent('Config.NoConfigurationFile', array($e), $pending = true);
-            $exceptionToThrow = $e;
+        } catch (Exception $exception) {
+
+            /**
+             * This event is triggered in case no configuration file is available. This usually means Piwik is not
+             * installed yet. The event can be used to start the installation process or to display a custom error
+             * message.
+             */
+            Piwik_PostEvent('Config.NoConfigurationFile', array($exception), $pending = true);
+            $exceptionToThrow = $exception;
         }
         return $exceptionToThrow;
     }
@@ -273,17 +308,28 @@ public function init()
             try {
                 Db::createDatabaseObject();
                 Piwik_GetOption('TestingIfDatabaseConnectionWorked');
-            } catch (Exception $e) {
+            } catch (Exception $exception) {
                 if (self::shouldRethrowException()) {
-                    throw $e;
+                    throw $exception;
                 }
-                Piwik_PostEvent('Config.badConfigurationFile', array($e), $pending = true);
-                throw $e;
+
+                /**
+                 * This event is triggered in case a config file is not in the correct format or in case required values
+                 * are missing. The event can be used to start the installation process or to display a custom error
+                 * message.
+                 */
+                Piwik_PostEvent('Config.badConfigurationFile', array($exception), $pending = true);
+                throw $exception;
             }
 
             // Init the Access object, so that eg. core/Updates/* can enforce Super User and use some APIs
             Access::getInstance();
 
+            /**
+             * This event is triggered after the platform is initialized and most plugins are loaded. The user is not
+             * authenticated at this point though. You can use this event for instance to initialize your own plugin.
+             * @matt
+             */
             Piwik_PostEvent('Request.dispatchCoreAndPluginUpdatesScreen');
 
             PluginsManager::getInstance()->installLoadedPlugins();
@@ -293,6 +339,11 @@ public function init()
                 $host = SettingsPiwik::getPiwikUrl();
             }
 
+            /**
+             * 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.
+             */
             Piwik_PostEvent('Request.initAuthenticationObject');
             try {
                 $authAdapter = Registry::get('auth');
@@ -314,6 +365,11 @@ public function init()
             Translate::getInstance()->reloadLanguage();
             $pluginsManager->postLoadPlugins();
 
+            /**
+             * This event is triggered to check for updates. It is triggered after the platform is initialized and after
+             * the user is authenticated but before the platform is going to dispatch the actual request. You can use
+             * it to check for any updates.
+             */
             Piwik_PostEvent('Updater.checkForUpdates');
         } catch (Exception $e) {