From 9bfd1ae2fefcb896b46573de64b62a7fc5980f8f Mon Sep 17 00:00:00 2001 From: Thomas Steur Date: Tue, 8 Oct 2013 02:56:55 +0000 Subject: [PATCH] refs #4199 documented some events --- core/.htaccess | 13 +++++++ core/AssetManager.php | 42 ++++++++++++++++++++++ core/Db.php | 11 ++++++ core/FrontController.php | 78 ++++++++++++++++++++++++++++++++++------ 4 files changed, 133 insertions(+), 11 deletions(-) create mode 100644 core/.htaccess diff --git a/core/.htaccess b/core/.htaccess new file mode 100644 index 00000000000..6cd2e134ec2 --- /dev/null +++ b/core/.htaccess @@ -0,0 +1,13 @@ + + +Deny from all + + + +Deny from all + + + +Deny from all + + diff --git a/core/AssetManager.php b/core/AssetManager.php index 2c80ab6c8af..c92a0508ed6 100644 --- a/core/AssetManager.php +++ b/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; diff --git a/core/Db.php b/core/Db.php index cb9224c76c1..059659562df 100644 --- a/core/Db.php +++ b/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']; diff --git a/core/FrontController.php b/core/FrontController.php index 7f93fd444be..0545f6f6694 100644 --- a/core/FrontController.php +++ b/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) {