From c2cb04094b439f50911d5656400e002f6f1563db Mon Sep 17 00:00:00 2001 From: Thomas Steur Date: Tue, 8 Oct 2013 03:42:28 +0000 Subject: [PATCH] refs #4199 documented some more events --- core/.htaccess | 13 --------- core/API/Proxy.php | 45 ++++++++++++++++++++++++++++++++ core/API/Request.php | 6 +++++ core/ArchiveProcessor/Day.php | 15 +++++++++++ core/ArchiveProcessor/Period.php | 15 +++++++++++ core/Db/Schema.php | 3 +++ core/FrontController.php | 2 +- core/Menu/Admin.php | 21 +++++++++++++++ core/Menu/Main.php | 21 +++++++++++++++ core/Menu/Top.php | 21 +++++++++++++++ 10 files changed, 148 insertions(+), 14 deletions(-) delete mode 100644 core/.htaccess diff --git a/core/.htaccess b/core/.htaccess deleted file mode 100644 index 6cd2e134ec2..00000000000 --- a/core/.htaccess +++ /dev/null @@ -1,13 +0,0 @@ - - -Deny from all - - - -Deny from all - - - -Deny from all - - diff --git a/core/API/Proxy.php b/core/API/Proxy.php index 1f9dc2a6b72..0a661eb30cf 100644 --- a/core/API/Proxy.php +++ b/core/API/Proxy.php @@ -180,7 +180,19 @@ public function call($className, $methodName, $parametersRequest) // allow plugins to manipulate the value $pluginName = $this->getModuleNameFromClassName($className); + /** + * Generic hook that plugins can use to modify any input to any API method. You could also use this to build + * an enhanced permission system. The event is triggered shortly before any API method is executed. + * + * The `$fnalParameters` contains all paramteres that will be passed to the actual API method. + */ Piwik_PostEvent(sprintf('API.Request.dispatch', $pluginName, $methodName), array(&$finalParameters)); + + /** + * This event is similar to the `API.Request.dispatch` event. It distinguishes the possibility to subscribe + * only to a specific API method instead of all API methods. You can use it for example to modify any input + * parameters or to execute any other logic before the actual API method is called. + */ Piwik_PostEvent(sprintf('API.%s.%s', $pluginName, $methodName), array(&$finalParameters)); // call the method @@ -193,7 +205,40 @@ public function call($className, $methodName, $parametersRequest) 'action' => $methodName, 'parameters' => $finalParameters) ); + + /** + * This event is similar to the `API.Request.dispatch.end` event. It distinguishes the possibility to + * subscribe only to the end of a specific API method instead of all API methods. You can use it for example + * to modify the response. The passed parameters contains the returned value as well as some additional + * meta information: + * + * ``` + * function ( + * &$returnedValue, + * array('className' => $className, + * 'module' => $pluginName, + * 'action' => $methodName, + * 'parameters' => $finalParameters) + * ); + * ``` + */ Piwik_PostEvent(sprintf('API.%s.%s.end', $pluginName, $methodName), $endHookParams); + + /** + * Generic hook that plugins can use to modify any output of any API method. The event is triggered after + * any API method is executed but before the result is send to the user. The parameters originally + * passed to the controller are available as well: + * + * ``` + * function ( + * &$returnedValue, + * array('className' => $className, + * 'module' => $pluginName, + * 'action' => $methodName, + * 'parameters' => $finalParameters) + * ); + * ``` + */ Piwik_PostEvent(sprintf('API.Request.dispatch.end', $pluginName, $methodName), $endHookParams); // Restore the request diff --git a/core/API/Request.php b/core/API/Request.php index 2d41682b7d8..d9b470beff7 100644 --- a/core/API/Request.php +++ b/core/API/Request.php @@ -181,6 +181,12 @@ static public function reloadAuthUsingTokenAuth($request = null) // if a token_auth is specified in the API request, we load the right permissions $token_auth = Common::getRequestVar('token_auth', '', 'string', $request); if ($token_auth) { + + /** + * 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. + * @matt + */ Piwik_PostEvent('API.Request.authenticate', array($token_auth)); Access::getInstance()->reloadAccess(); SettingsServer::raiseMemoryLimitIfNecessary(); diff --git a/core/ArchiveProcessor/Day.php b/core/ArchiveProcessor/Day.php index 769274d4cfb..c0732d9885a 100644 --- a/core/ArchiveProcessor/Day.php +++ b/core/ArchiveProcessor/Day.php @@ -104,6 +104,21 @@ protected function convertMetricsIdToName($data) protected function compute() { + /** + * This event is triggered when the archiver wants to compute a new archive. Use this event to archive your + * custom report data if needed. + * + * Example: + * ``` + * public function archiveDay(ArchiveProcessor\Day $archiveProcessor) + * { + * $archiving = new Archiver($archiveProcessor); + * if ($archiving->shouldArchive()) { + * $archiving->archiveDay(); + * } + * } + * ``` + */ Piwik_PostEvent('ArchiveProcessor.Day.compute', array(&$this)); } } diff --git a/core/ArchiveProcessor/Period.php b/core/ArchiveProcessor/Period.php index 6807d013464..c2c48db8a80 100644 --- a/core/ArchiveProcessor/Period.php +++ b/core/ArchiveProcessor/Period.php @@ -186,6 +186,21 @@ protected function getRecordDataTableSum($name, $invalidSummedColumnNameToRename protected function compute() { + /** + * This event is triggered when the archiver wants to compute a new archive. Use this event to archive your + * custom report data if needed. + * + * Example: + * ``` + * public function archiveDay(ArchiveProcessor\Day $archiveProcessor) + * { + * $archiving = new Archiver($archiveProcessor); + * if ($archiving->shouldArchive()) { + * $archiving->archivePeriod(); + * } + * } + * ``` + */ Piwik_PostEvent('ArchiveProcessor.Period.compute', array(&$this)); } diff --git a/core/Db/Schema.php b/core/Db/Schema.php index 4a86ce97638..acf71e6a6ae 100644 --- a/core/Db/Schema.php +++ b/core/Db/Schema.php @@ -131,6 +131,9 @@ public static function getSchemas($adapterName) private function loadSchema() { $schema = null; + /** + * @matt can be removed? + */ Piwik_PostEvent('Schema.loadSchema', array(&$schema)); if ($schema === null) { $config = Config::getInstance(); diff --git a/core/FrontController.php b/core/FrontController.php index 0545f6f6694..1ccb606321d 100644 --- a/core/FrontController.php +++ b/core/FrontController.php @@ -128,7 +128,7 @@ public function dispatch($module = null, $action = null, $parameters = null) * 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)` + * The `$params` array contains the following properties: `array($module, $action, $parameters, $controller)` */ Piwik_PostEvent('Request.dispatch', $params); diff --git a/core/Menu/Admin.php b/core/Menu/Admin.php index 67b9187d8c0..ddf6462da2c 100644 --- a/core/Menu/Admin.php +++ b/core/Menu/Admin.php @@ -39,6 +39,27 @@ static public function getInstance() public function get() { if (!$this->menu) { + + /** + * 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. + * + * Example: + * ``` + * public function addMenuItems() + * { + * Piwik_AddAdminSubMenu( + * 'MenuName', + * 'SubmenuName', + * array('module' => 'MyPlugin', 'action' => 'index'), + * Piwik::isUserIsSuperUser(), + * $order = 6 + * ); + * } + * ``` + */ Piwik_PostEvent('Menu.Admin.addItems'); } return parent::get(); diff --git a/core/Menu/Main.php b/core/Menu/Main.php index 828f82517ae..236379078f1 100644 --- a/core/Menu/Main.php +++ b/core/Menu/Main.php @@ -59,6 +59,27 @@ public function get() { // We trigger the Event only once! if (!$this->menu) { + + /** + * 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. + * + * Example: + * ``` + * public function addMenuItems() + * { + * Piwik_AddMenu( + * 'CustomMenuName', + * 'CustomSubmenuName', + * array('module' => 'MyPlugin', 'action' => 'index'), + * Piwik::isUserIsSuperUser(), + * $order = 6 + * ); + * } + * ``` + */ Piwik_PostEvent('Menu.Reporting.addItems'); } return parent::get(); diff --git a/core/Menu/Top.php b/core/Menu/Top.php index 31c8fbb86af..98087916a47 100644 --- a/core/Menu/Top.php +++ b/core/Menu/Top.php @@ -59,6 +59,27 @@ public function addHtml($menuName, $data, $displayedForCurrentUser, $order, $too public function get() { if (!$this->menu) { + + /** + * This event is triggered to collect all available menu items that should be displayed on the very top next + * to login/logout, API and other menu items. Subscribe to this event if you want to add one or more items. + * 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. + * + * Example: + * ``` + * public function addMenuItems() + * { + * Piwik_AddTopMenu( + * 'TopMenuName', + * array('module' => 'MyPlugin', 'action' => 'index'), + * Piwik::isUserIsSuperUser(), + * $order = 6 + * ); + * } + * ``` + */ Piwik_PostEvent('Menu.Top.addItems'); } return parent::get();