diff options
| author | diosmosis <benakamoorthi@fastmail.fm> | 2013-12-06 01:49:56 +0400 |
|---|---|---|
| committer | diosmosis <benakamoorthi@fastmail.fm> | 2013-12-06 01:49:56 +0400 |
| commit | 777ca60440aa67e436fb15bb0fc1bd445d32ce78 (patch) | |
| tree | e3557a53472016259873109e2932f99b764be42c | |
| parent | b6c2cf90277b6abeabe13910b04ef286c66a4b67 (diff) | |
Fixes #4199, revising event docs and closing ticket.
36 files changed, 544 insertions, 363 deletions
diff --git a/core/API/Proxy.php b/core/API/Proxy.php index 9e4d193b3b..43faca7063 100644 --- a/core/API/Proxy.php +++ b/core/API/Proxy.php @@ -168,27 +168,40 @@ class Proxy extends Singleton /** * Triggered before an API request is dispatched. * - * This event can be used to modify the input that is passed to every API method or just - * one. + * This event can be used to modify the arguments passed to one or more API methods. + * + * **Example** + * + * Piwik::addAction('API.Request.dispatch', function (&$parameters, $pluginName, $methodName) { + * if ($pluginName == 'Actions') { + * if ($methodName == 'getPageUrls') { + * // ... do something ... + * } else { + * // ... do something else ... + * } + * } + * }); * * @param array &$finalParameters List of parameters that will be passed to the API method. - * @param string $pluginName The name of the plugin being dispatched to. + * @param string $pluginName The name of the plugin the API method belongs to. * @param string $methodName The name of the API method that will be called. */ Piwik::postEvent('API.Request.dispatch', array(&$finalParameters, $pluginName, $methodName)); /** + * Triggered before an API request is dispatched. + * * This event exists for convenience and is triggered directly after the {@hook API.Request.dispatch} - * event is triggered. + * event is triggered. It can be used to modify the arguments passed to a **single** API method. * - * It can be used to modify the input that is passed to a single API method. This is also - * possible with the {@hook API.Request.dispatch} event, however that event requires event handlers - * check if the plugin name and method name are correct before modifying the parameters. + * _Note: This is can be accomplished with the {@hook API.Request.dispatch} event as well, however + * event handlers for that event will have to do more work._ * * **Example** * * Piwik::addAction('API.Actions.getPageUrls', function (&$parameters) { - * // ... + * // force use of a single website. for some reason. + * $parameters['idSite'] = 1; * }); * * @param array &$finalParameters List of parameters that will be passed to the API method. @@ -207,21 +220,36 @@ class Proxy extends Singleton ); /** + * Triggered directly after an API request is dispatched. + * * This event exists for convenience and is triggered immediately before the - * {@hook API.Request.dispatch.end} event. + * {@hook API.Request.dispatch.end} event. It can be used to modify the output of a **single** + * API method. * - * It can be used to modify the output of a single API method. This is also possible with - * the {@hook API.Request.dispatch.end} event, however that event requires event handlers - * check if the plugin name and method name are correct before modifying the output. + * _Note: This can be accomplished with the {@hook API.Request.dispatch.end} event as well, + * however event handlers for that event will have to do more work._ * - * @param mixed &$returnedValue The value returned from the API method. This will not be - * a rendered string, but an actual object. For example, it + * **Example** + * + * // append (0 hits) to the end of row labels whose row has 0 hits + * Piwik::addAction('API.Actions.getPageUrls', function (&$returnValue, $info)) { + * $returnValue->filter('ColumnCallbackReplace', 'label', function ($label, $hits) { + * if ($hits === 0) { + * return $label . " (0 hits)"; + * } else { + * return $label; + * } + * }, null, array('nb_hits')); + * } + * + * @param mixed &$returnedValue The API method's return value. Can be an object, such as a + * {@link Piwik\DataTable DataTable} instance. * could be a {@link Piwik\DataTable DataTable}. * @param array $extraInfo An array holding information regarding the API request. Will * contain the following data: * - * - **className**: The name of the namespace-d class name of the - * API instance that's being called. + * - **className**: The namespace-d class name of the API instance + * that's being called. * - **module**: The name of the plugin the API request was * dispatched to. * - **action**: The name of the API method that was executed. @@ -235,14 +263,33 @@ class Proxy extends Singleton * * This event can be used to modify the output of any API method. * - * @param mixed &$returnedValue The value returned from the API method. This will not be - * a rendered string, but an actual object. For example, it - * could be a {@link Piwik\DataTable}. + * **Example** + * + * // append (0 hits) to the end of row labels whose row has 0 hits for any report that has the 'nb_hits' metric + * Piwik::addAction('API.Actions.getPageUrls', function (&$returnValue, $info)) { + * // don't process non-DataTable reports and reports that don't have the nb_hits column + * if (!($returnValue instanceof DataTableInterface) + * || in_array('nb_hits', $returnValue->getColumns()) + * ) { + * return; + * } + * + * $returnValue->filter('ColumnCallbackReplace', 'label', function ($label, $hits) { + * if ($hits === 0) { + * return $label . " (0 hits)"; + * } else { + * return $label; + * } + * }, null, array('nb_hits')); + * } + * + * @param mixed &$returnedValue The API method's return value. Can be an object, such as a + * {@link Piwik\DataTable DataTable} instance. * @param array $extraInfo An array holding information regarding the API request. Will * contain the following data: * - * - **className**: The name of the namespace-d class name of the - * API instance that's being called. + * - **className**: The namespace-d class name of the API instance + * that's being called. * - **module**: The name of the plugin the API request was * dispatched to. * - **action**: The name of the API method that was executed. diff --git a/core/API/Request.php b/core/API/Request.php index 50f8d64ec3..76ee0791be 100644 --- a/core/API/Request.php +++ b/core/API/Request.php @@ -238,11 +238,11 @@ class Request if ($token_auth) { /** - * Triggered when authenticating an API request. Only triggered if the **token_auth** + * Triggered when authenticating an API request, but only if the **token_auth** * query parameter is found in the request. * * Plugins that provide authentication capabilities should subscribe to this event - * and make sure the authentication object (the object returned by `Registry::get('auth')`) + * and make sure the global authentication object (the object returned by `Registry::get('auth')`) * is setup to use `$token_auth` when its `authenticate()` method is executed. * * @param string $token_auth The value of the **token_auth** query parameter. diff --git a/core/Access.php b/core/Access.php index 7dfb25bb51..86a4a04cf5 100644 --- a/core/Access.php +++ b/core/Access.php @@ -427,11 +427,12 @@ class Access } /** - * Exception thrown when a user doesn't have sufficient access. + * Exception thrown when a user doesn't have sufficient access to a resource. * * @package Piwik * @subpackage Access + * @api */ class NoAccessException extends \Exception { -} +}
\ No newline at end of file diff --git a/core/ArchiveProcessor/Parameters.php b/core/ArchiveProcessor/Parameters.php index db8919228c..7ac9129b3b 100644 --- a/core/ArchiveProcessor/Parameters.php +++ b/core/ArchiveProcessor/Parameters.php @@ -101,7 +101,7 @@ class Parameters $idSites = array($idSite); - Piwik::postEvent('ArchiveProcessor.Parameters.getIdSites', array( &$idSites, $this->getPeriod() ) ); + Piwik::postEvent('ArchiveProcessor.Parameters.getIdSites', array(&$idSites, $this->getPeriod())); return $idSites; } diff --git a/core/AssetManager.php b/core/AssetManager.php index 915bb5f07e..ec850de0db 100644 --- a/core/AssetManager.php +++ b/core/AssetManager.php @@ -163,7 +163,7 @@ class AssetManager * * This event can be used to modify merged CSS. * - * @param string &$mergedContent The merged an minified CSS. + * @param string &$mergedContent The merged and minified CSS. */ Piwik::postEvent('AssetManager.filterMergedStylesheets', array(&$mergedContent)); @@ -295,12 +295,12 @@ class AssetManager * Plugins that have stylesheets should use this event to make those stylesheets * load. * - * Stylesheets should be placed within a **stylesheets** subfolder in your plugin's + * Stylesheets should be placed within a **stylesheets** subdirectory in your plugin's * root directory. * - * Note: In case you are developing your plugin you may enable the config setting - * `[Debug] disable_merged_assets`. Otherwise your custom stylesheets won't be - * reloaded immediately after a change. + * _Note: While you are developing your plugin you should enable the config setting + * `[Debug] disable_merged_assets` so your stylesheets will be reloaded immediately + * after a change._ * * **Example** * @@ -382,7 +382,7 @@ class AssetManager $mergedContent = str_replace("\n", "\r\n", $mergedContent); /** - * Triggered after all JavaScript files Piwik uses are minified and merged into a + * Triggered after all the JavaScript files Piwik uses are minified and merged into a * single file, but before the merged JavaScript is written to disk. * * Plugins can use this event to modify merged JavaScript or do something else @@ -431,19 +431,19 @@ class AssetManager * Plugins that have their own JavaScript should use this event to make those * files load in the browser. * - * JavaScript files should be placed within a **javascripts** subfolder in your + * JavaScript files should be placed within a **javascripts** subdirectory in your * plugin's root directory. * - * Note: In case you are developing your plugin you may enable the config setting - * `[Debug] disable_merged_assets`. Otherwise your JavaScript won't be reloaded - * immediately after a change. + * _Note: While you are developing your plugin you should enable the config setting + * `[Debug] disable_merged_assets` so JavaScript files will be reloaded immediately + * after every change._ * * **Example** * - * public function getJsFiles(&jsFiles) + * public function getJsFiles(&$jsFiles) * { - * jsFiles[] = "plugins/MyPlugin/javascripts/myfile.js"; - * jsFiles[] = "plugins/MyPlugin/javascripts/anotherone.js"; + * $jsFiles[] = "plugins/MyPlugin/javascripts/myfile.js"; + * $jsFiles[] = "plugins/MyPlugin/javascripts/anotherone.js"; * } * * @param string[] $jsFiles The JavaScript files to load. @@ -710,4 +710,4 @@ class AssetManager { return "/* Piwik Javascript - cb=" . self::generateAssetsCacheBuster() . "*/\n"; } -} +}
\ No newline at end of file diff --git a/core/Console.php b/core/Console.php index 15ecbc18bc..1547d6aec0 100644 --- a/core/Console.php +++ b/core/Console.php @@ -48,18 +48,17 @@ class Console $commands = array(); /** - * Triggered when gathering all available console commands. Plugins that want to expose new console commands + * Triggered to gather all available console commands. Plugins that want to expose new console commands * should subscribe to this event and add commands to the incoming array. * * **Example** - * ``` - * public function addConsoleCommands(&$commands) - * { - * $commands[] = 'Piwik\Plugins\MyPlugin\Commands\MyCommand'; - * } - * ``` + * + * public function addConsoleCommands(&$commands) + * { + * $commands[] = 'Piwik\Plugins\MyPlugin\Commands\MyCommand'; + * } * - * @param array &$commands An array containing a list of command classnames. + * @param array &$commands An array containing a list of command class names. */ Piwik::postEvent('Console.addCommands', array(&$commands)); diff --git a/core/CronArchive.php b/core/CronArchive.php index f3d7485800..9298a01f8d 100644 --- a/core/CronArchive.php +++ b/core/CronArchive.php @@ -795,8 +795,13 @@ Notes: $websiteIds = array_intersect($websiteIds, $this->allWebsites); /** - * When the cron to run archive.php is executed, it fetches the list of website IDs to process. - * Use this hook to add, remove, or change the order of websites IDs to pre-archive. + * Triggered by the **archive.php** cron script so plugins can modify the list of + * websites that the archiving process will be launched for. + * + * Plugins can use this hook to add websites to archive, remove websites to archive, or change + * the order in which websites will be archived. + * + * @param array $websiteIds The list of website IDs to launch the archiving process for. */ Piwik::postEvent('CronArchive.filterWebsiteIds', array(&$websiteIds)); } diff --git a/core/Db.php b/core/Db.php index f71b64742c..a1ae66916d 100644 --- a/core/Db.php +++ b/core/Db.php @@ -74,21 +74,21 @@ class Db } /** - * Triggered before a connection to the database is established. + * Triggered before a database connection is established. * - * This event can be used to dynamically change the settings used to connect to the - * database. + * This event can be used to change the settings used to establish a connection. * - * @param array $dbInfos Reference to an array containing database connection info, - * including: - * - **host**: The host name or IP address to the MySQL database. - * - **username**: The username to use when connecting to the - * database. - * - **password**: The password to use when connecting to the + * @param array *$dbInfos Reference to an array containing database connection info, + * including: + * + * - **host**: The host name or IP address to the MySQL database. + * - **username**: The username to use when connecting to the + * database. + * - **password**: The password to use when connecting to the * database. - * - **dbname**: The name of the Piwik MySQL database. - * - **port**: The MySQL database port to use. - * - **adapter**: either `'PDO_MYSQL'` or `'MYSQLI'` + * - **dbname**: The name of the Piwik MySQL database. + * - **port**: The MySQL database port to use. + * - **adapter**: either `'PDO_MYSQL'` or `'MYSQLI'` */ Piwik::postEvent('Reporting.getDatabaseConfig', array(&$dbInfos)); diff --git a/core/FrontController.php b/core/FrontController.php index dbd3bb86d4..e9fb8f6093 100644 --- a/core/FrontController.php +++ b/core/FrontController.php @@ -91,7 +91,7 @@ class FrontController extends Singleton * Triggered directly before controller actions are dispatched. * * This event can be used to modify the parameters passed to one or more controller actions - * and can be used to change the plugin and action that is being dispatched to. + * and can be used to change the controller action being dispatched to. * * @param string &$module The name of the plugin being dispatched to. * @param string &$action The name of the controller method being dispatched to. @@ -102,6 +102,8 @@ class FrontController extends Singleton list($controller, $action) = $this->makeController($module, $action); /** + * Triggered directly before controller actions are dispatched. + * * This event exists for convenience and is triggered directly after the {@hook Request.dispatch} * event is triggered. * @@ -116,6 +118,8 @@ class FrontController extends Singleton $result = call_user_func_array(array($controller, $action), $parameters); /** + * Triggered after a controller action is successfully called. + * * This event exists for convenience and is triggered immediately before the {@hook Request.dispatch.end} * event is triggered. * @@ -131,10 +135,9 @@ class FrontController extends Singleton /** * Triggered after a controller action is successfully called. * - * This event can be used to modify controller action output (if there was any) before - * the output is returned. + * This event can be used to modify controller action output (if any) before the output is returned. * - * @param mixed &$result The result of the controller action. + * @param mixed &$result The controller action result. * @param array $parameters The arguments passed to the controller action. */ Piwik::postEvent('Request.dispatch.end', array(&$result, $parameters)); @@ -255,9 +258,10 @@ class FrontController extends Singleton } catch (Exception $exception) { /** - * Triggered when the configuration file cannot be found or read. This usually - * means Piwik is not installed yet. This event can be used to start the - * installation process or to display a custom error message. + * Triggered when the configuration file cannot be found or read, which usually + * means Piwik is not installed yet. + * + * This event can be used to start the installation process or to display a custom error message. * * @param Exception $exception The exception that was thrown by `Config::getInstance()`. */ @@ -335,8 +339,9 @@ class FrontController extends Singleton /** * Triggered if the INI config file has the incorrect format or if certain required configuration - * options are absent. This event can be used to start the installation process or to display a - * custom error message. + * options are absent. + * + * This event can be used to start the installation process or to display a custom error message. * * @param Exception $exception The exception thrown from creating and testing the database * connection. @@ -350,8 +355,10 @@ class FrontController extends Singleton /** * Triggered just after the platform is initialized and plugins are loaded. - * This event can be used to do early initialization. Note: At this point the user - * is not authenticated yet. + * + * This event can be used to do early initialization. + * + * _Note: At this point the user is not authenticated yet._ */ Piwik::postEvent('Request.dispatchCoreAndPluginUpdatesScreen'); @@ -363,9 +370,17 @@ class FrontController extends Singleton } /** - * Triggered before the user is authenticated. You can use it to create your own - * authentication object which implements the {@link Piwik\Auth} interface and overrides - * the default authentication logic. + * Triggered before the user is authenticated, when the global authentication object + * should be created. + * + * Plugins that provide their own authentication implementation should use this event + * to set the global authentication object (which must derive from {@link Piwik\Auth}). + * + * **Example** + * + * Piwik::addAction('Request.initAuthenticationObject', function() { + * Piwik\Registry::set('auth', new MyAuthImplementation()); + * }); */ Piwik::postEvent('Request.initAuthenticationObject'); try { @@ -390,7 +405,7 @@ class FrontController extends Singleton /** * Triggered after the platform is initialized and after the user has been authenticated, but - * before the platform dispatched the request. + * before the platform has handled the request. * * Piwik uses this event to check for updates to Piwik. */ diff --git a/core/Log.php b/core/Log.php index bdf4ac23c7..b2facc6cb6 100644 --- a/core/Log.php +++ b/core/Log.php @@ -302,17 +302,19 @@ class Log extends Singleton * This event is called when the Log instance is created. Plugins can use this event to * make new logging writers available. * - * A logging writer is a callback that takes the following arguments: - * int $level, string $tag, string $datetime, string $message + * A logging writer is a callback with the following signature: + * + * function (int $level, string $tag, string $datetime, string $message) * - * $level is the log level to use, $tag is the log tag used, $datetime is the date time - * of the logging call and $message is the formatted log message. + * `$level` is the log level to use, `$tag` is the log tag used, `$datetime` is the date time + * of the logging call and `$message` is the formatted log message. * - * Logging writers must be associated by name in the array passed to event handlers. + * Logging writers must be associated by name in the array passed to event handlers. The + * name specified can be used in Piwik's INI configuration. * - * ***Example** + * **Example** * - * function (&$writers) { + * public function getAvailableWriters(&$writers) { * $writers['myloggername'] = function ($level, $tag, $datetime, $message) { * // ... * }; @@ -320,7 +322,7 @@ class Log extends Singleton * * // 'myloggername' can now be used in the log_writers config option. * - * @param $ + * @param array $writers Array mapping writer names with logging writers. */ Piwik::postEvent(self::GET_AVAILABLE_WRITERS_EVENT, array(&$writers)); @@ -338,12 +340,20 @@ class Log extends Singleton $logger = $this; /** - * This event is called when trying to log an object to a file. Plugins can use + * Triggered when trying to log an object to a file. Plugins can use * this event to convert objects to strings before they are logged. * + * **Example** + * + * public function formatFileMessage(&$message, $level, $tag, $datetime, $logger) { + * if ($message instanceof MyCustomDebugInfo) { + * $message = $message->formatForFile(); + * } + * } + * * @param mixed &$message The object that is being logged. Event handlers should * check if the object is of a certain type and if it is, - * set $message to the string that should be logged. + * set `$message` to the string that should be logged. * @param int $level The log level used with this log entry. * @param string $tag The current plugin that started logging (or if no plugin, * the current class). @@ -387,15 +397,23 @@ class Log extends Singleton $logger = $this; /** - * This event is called when trying to log an object to the screen. Plugins can use + * Triggered when trying to log an object to the screen. Plugins can use * this event to convert objects to strings before they are logged. * * The result of this callback can be HTML so no sanitization is done on the result. - * This means YOU MUST SANITIZE THE MESSAGE YOURSELF if you use this event. + * This means **YOU MUST SANITIZE THE MESSAGE YOURSELF** if you use this event. * + * **Example** + * + * public function formatScreenMessage(&$message, $level, $tag, $datetime, $logger) { + * if ($message instanceof MyCustomDebugInfo) { + * $message = Common::sanitizeInputValue($message->formatForScreen()); + * } + * } + * * @param mixed &$message The object that is being logged. Event handlers should * check if the object is of a certain type and if it is, - * set $message to the string that should be logged. + * set `$message` to the string that should be logged. * @param int $level The log level used with this log entry. * @param string $tag The current plugin that started logging (or if no plugin, * the current class). @@ -420,12 +438,20 @@ class Log extends Singleton $logger = $this; /** - * This event is called when trying to log an object to a database table. Plugins can use + * Triggered when trying to log an object to a database table. Plugins can use * this event to convert objects to strings before they are logged. * + * **Example** + * + * public function formatDatabaseMessage(&$message, $level, $tag, $datetime, $logger) { + * if ($message instanceof MyCustomDebugInfo) { + * $message = $message->formatForDatabase(); + * } + * } + * * @param mixed &$message The object that is being logged. Event handlers should * check if the object is of a certain type and if it is, - * set $message to the string that should be logged. + * set `$message` to the string that should be logged. * @param int $level The log level used with this log entry. * @param string $tag The current plugin that started logging (or if no plugin, * the current class). diff --git a/core/Menu/MenuTop.php b/core/Menu/MenuTop.php index 8e2caba4a5..e9d5dc6f52 100644 --- a/core/Menu/MenuTop.php +++ b/core/Menu/MenuTop.php @@ -92,8 +92,9 @@ class MenuTop extends MenuAbstract /** * Triggered when collecting all available menu items that are be displayed on the very top of every - * page, next to the login/logout links. Subscribe to this event if you want to add one or more items - * to the top menu. + * page, next to the login/logout links. + * + * Subscribe to this event if you want to add one or more items to the top menu. * * Menu items should be added via the {@link addEntry()} method. * diff --git a/core/Plugin/ViewDataTable.php b/core/Plugin/ViewDataTable.php index 204c25a9fa..b3b64ac05a 100644 --- a/core/Plugin/ViewDataTable.php +++ b/core/Plugin/ViewDataTable.php @@ -124,13 +124,14 @@ abstract class ViewDataTable implements ViewInterface /** * Triggered during {@link ViewDataTable} construction. Subscribers should customize - * the view based on the report that it is displaying. + * the view based on the report that is being displayed. * * Plugins that define their own reports must subscribe to this event in order to - * specify how the Piwik UI will display the report. + * specify how the Piwik UI should display the report. * * **Example** * + * // event handler * public function configureViewDataTable(ViewDataTable $view) * { * switch ($view->requestConfig->apiMethodToRequestDataTable) { diff --git a/core/SettingsPiwik.php b/core/SettingsPiwik.php index 941f9af920..58ac848a9a 100644 --- a/core/SettingsPiwik.php +++ b/core/SettingsPiwik.php @@ -65,23 +65,29 @@ class SettingsPiwik /** * Triggered during the cron archiving process to collect segments that * should be pre-processed for all websites. The archiving process will be launched - * for each of these segments when archiving data for each site. + * for each of these segments when archiving data. * - * This event can be used to add segments to be pre-processed. This can be provide - * enhanced performance if your plugin depends on data from a specific segment. + * This event can be used to add segments to be pre-processed. If your plugin depends + * on data from a specific segment, this event could be used to provide enhanced + * performance. * - * Note: If you just want to add a segment that is managed by the user, you should use the - * SegmentEditor API. + * _Note: If you just want to add a segment that is managed by the user, use the + * SegmentEditor API._ + * + * **Example** + * + * Piwik::addAction('Segments.getKnownSegmentsToArchiveAllSites', function (&$segments) { + * $segments[] = 'country=jp;city=Tokyo'; + * }); * * @param array &$segmentsToProcess List of segment definitions, eg, - * ``` - * array( - * 'browserCode=ff;resolution=800x600', - * 'country=JP;city=Tokyo' - * ) - * ``` - * Add segments to process to this array in your event - * handler. + * + * array( + * 'browserCode=ff;resolution=800x600', + * 'country=jp;city=Tokyo' + * ) + * + * Add segments to this array in your event handler. */ Piwik::postEvent('Segments.getKnownSegmentsToArchiveAllSites', array(&$segmentsToProcess)); @@ -107,21 +113,25 @@ class SettingsPiwik * should be pre-processed for one specific site. The archiving process will be launched * for each of these segments when archiving data for that one site. * - * This event can be used to add segments to be pre-processed. This can be provide - * enhanced performance if your plugin depends on data from a specific segment. + * This event can be used to add segments to be pre-processed for one site. + * + * _Note: If you just want to add a segment that is managed by the user, you should use the + * SegmentEditor API._ + * + * **Example** * - * Note: If you just want to add a segment that is managed by the user, you should use the - * SegmentEditor API. + * Piwik::addAction('Segments.getKnownSegmentsToArchiveForSite', function (&$segments, $idSite) { + * $segments[] = 'country=jp;city=Tokyo'; + * }); * * @param array &$segmentsToProcess List of segment definitions, eg, - * ``` - * array( - * 'browserCode=ff;resolution=800x600', - * 'country=JP;city=Tokyo' - * ) - * ``` - * Add segments to process to this array in your event - * handler. + * + * array( + * 'browserCode=ff;resolution=800x600', + * 'country=JP;city=Tokyo' + * ) + * + * Add segments to this array in your event handler. * @param int $idSite The ID of the site to get segments for. */ Piwik::postEvent('Segments.getKnownSegmentsToArchiveForSite', array(&$segments, $idSite)); diff --git a/core/Site.php b/core/Site.php index 38b9c32410..6e4e9c4753 100644 --- a/core/Site.php +++ b/core/Site.php @@ -92,14 +92,21 @@ class Site throw new Exception("Un unexpected website was found."); } - /** - * Piwik core APIs and plugins use the Site object to get information about websites. - * This event is called just before a Website information is stored in the memory cache. - * It can be used to modify the data for a website, such as decorate its name or change its created datetime. + * Triggered so plugins can modify website entities without modifying the database. + * + * This event should **not** be used to add data that is expensive to compute. If you + * need to make HTTP requests or query the database for more information, this is not + * the place to do it. * - * @param int $idSite Website ID - * @param array $infoSite Website information array + * **Example** + * + * Piwik::addAction('Site.setSite', function ($idSite, &$info) { + * $info['name'] .= " (original)"; + * }); + * + * @param int $idSite The ID of the website entity that will be modified. + * @param array $infoSite The website entity. [Learn more.](/guides/persistence-and-the-mysql-backend#websites-aka-sites) */ Piwik::postEvent('Site.setSite', array($idSite, &$infoSite)); diff --git a/core/TaskScheduler.php b/core/TaskScheduler.php index 5503f68340..05bc56de3a 100644 --- a/core/TaskScheduler.php +++ b/core/TaskScheduler.php @@ -79,26 +79,23 @@ class TaskScheduler $tasks = array(); /** - * Triggered when the TaskScheduler runs scheduled tasks. Collects all the tasks that - * will be run. + * Triggered during scheduled task execution. Collects all the tasks to run. * * Subscribe to this event to schedule code execution on an hourly, daily, weekly or monthly * basis. * * **Example** * - * ``` - * public function getScheduledTasks(&$tasks) - * { - * $tasks[] = new ScheduledTask( - * 'Piwik\Plugins\CorePluginsAdmin\MarketplaceApiClient', - * 'clearAllCacheEntries', - * null, - * ScheduledTime::factory('daily'), - * ScheduledTask::LOWEST_PRIORITY - * ); - * } - * ``` + * public function getScheduledTasks(&$tasks) + * { + * $tasks[] = new ScheduledTask( + * 'Piwik\Plugins\CorePluginsAdmin\MarketplaceApiClient', + * 'clearAllCacheEntries', + * null, + * ScheduledTime::factory('daily'), + * ScheduledTask::LOWEST_PRIORITY + * ); + * } * * @param ScheduledTask[] &$tasks List of tasks to run periodically. */ diff --git a/core/Tracker.php b/core/Tracker.php index 0e8b746b0f..abf396cbfd 100644 --- a/core/Tracker.php +++ b/core/Tracker.php @@ -523,13 +523,13 @@ class Tracker } /** - * Triggered before a connection to the database is established in the Tracker. + * Triggered before a connection to the database is established by the Tracker. * - * This event can be used to dynamically change the settings used to connect to the - * database. + * This event can be used to change the database connection settings used by the Tracker. * * @param array $dbInfos Reference to an array containing database connection info, * including: + * * - **host**: The host name or IP address to the MySQL database. * - **username**: The username to use when connecting to the * database. @@ -588,13 +588,13 @@ class Tracker $visit = null; /** - * Triggered before a new `{@link Piwik\Tracker\Visit}` object is created. Subscribers to this + * Triggered before a new **visit object** is created. Subscribers to this * event can force the use of a custom visit object that extends from * {@link Piwik\Tracker\VisitInterface}. * * @param \Piwik\Tracker\VisitInterface &$visit Initialized to null, but can be set to - * a created Visit object. If it isn't - * modified Piwik uses the default class. + * a new visit object. If it isn't modified + * Piwik uses the default class. */ Piwik::postEvent('Tracker.makeNewVisitObject', array(&$visit)); diff --git a/core/Tracker/Action.php b/core/Tracker/Action.php index 10c8514f05..71c090efd6 100644 --- a/core/Tracker/Action.php +++ b/core/Tracker/Action.php @@ -264,7 +264,7 @@ abstract class Action ? (int)$this->getIdActionName() : null; - $insert = array( + $visitAction = array( 'idvisit' => $idVisit, 'idsite' => $this->request->getIdSite(), 'idvisitor' => $visitorIdCookie, @@ -277,12 +277,12 @@ abstract class Action ); foreach($this->actionIdsCached as $field => $idAction) { - $insert[$field] = $idAction; + $visitAction[$field] = $idAction; } $customValue = $this->getCustomFloatValue(); if (!empty($customValue)) { - $insert[self::DB_COLUMN_CUSTOM_FLOAT] = $customValue; + $visitAction[self::DB_COLUMN_CUSTOM_FLOAT] = $customValue; } $customVariables = $this->getCustomVariables(); @@ -291,47 +291,27 @@ abstract class Action Common::printDebug($customVariables); } - $insert = array_merge($insert, $customVariables); - $fields = implode(", ", array_keys($insert)); - $bind = array_values($insert); - $values = Common::getSqlStringFieldsArray($insert); + $visitAction = array_merge($visitAction, $customVariables); + $fields = implode(", ", array_keys($visitAction)); + $bind = array_values($visitAction); + $values = Common::getSqlStringFieldsArray($visitAction); $sql = "INSERT INTO " . Common::prefixTable('log_link_visit_action') . " ($fields) VALUES ($values)"; Tracker::getDatabase()->query($sql, $bind); $this->idLinkVisitAction = Tracker::getDatabase()->lastInsertId(); + $visitAction['idlink_va'] = $this->idLinkVisitAction; - $info = array( - 'idSite' => $this->request->getIdSite(), - 'idLinkVisitAction' => $this->idLinkVisitAction, - 'idVisit' => $idVisit, - 'idReferrerActionUrl' => $idReferrerActionUrl, - 'idReferrerActionName' => $idReferrerActionName, - 'timeSpentReferrerAction' => $timeSpentReferrerAction, - ); Common::printDebug("Inserted new action:"); - Common::printDebug($insert); + Common::printDebug($visitAction); /** - * Triggered after successfully logging an action for a visit. - * + * Triggered after successfully persisting a [visit action entity](/guides/persistence-and-the-mysql-backend#visit-actions). * * @param Action $tracker Action The Action tracker instance. - * @param array $info An array describing the current visit action. Includes the - * following information: - * - **idSite**: The ID of the site that we are tracking. - * - **idLinkVisitAction**: The ID of the row that was inserted into the - * log_link_visit_action table. - * - **idVisit**: The visit ID. - * - **idReferrerActionUrl**: The ID referencing the row in the log_action table - * that holds the URL of the visitor's last action. - * - **idReferrerActionName**: The ID referencing the row in the log_action table - * that holds the name of the visitor's last action. - * - **timeSpentReferrerAction**: The number of seconds since the visitor's last - * action. + * @param array $visitAction The visit action entity that was persisted. Read + * [this](/guides/persistence-and-the-mysql-backend#visit-actions) to see what it contains. */ - Piwik::postEvent('Tracker.recordAction', array($trackerAction = $this, $info)); + Piwik::postEvent('Tracker.recordAction', array($trackerAction = $this, $visitAction)); } - -} - +}
\ No newline at end of file diff --git a/core/Tracker/Cache.php b/core/Tracker/Cache.php index 142c075ead..3b23d55442 100644 --- a/core/Tracker/Cache.php +++ b/core/Tracker/Cache.php @@ -70,8 +70,11 @@ class Cache $content = array(); /** - * This event is called to get the details of a site by its ID. It can be used to - * add custom attributes for the website to the Tracker cache. + * Triggered to get the attributes of a site entity that might be used by the + * Tracker. + * + * Plugins add new site attributes for use in other tracking events must + * use this event to put those attributes in the Tracker Cache. * * **Example** * @@ -81,8 +84,8 @@ class Cache * $content['myplugin_site_data'] = Db::fetchOne($sql, array($idSite)); * } * - * @param array &$content List of attributes. - * @param int $idSite The site ID. + * @param array &$content Array mapping of site attribute names with values. + * @param int $idSite The site ID to get attributes for. */ Piwik::postEvent('Tracker.Cache.getSiteAttributes', array(&$content, $idSite)); @@ -129,13 +132,14 @@ class Cache ); /** - * Triggered before the general tracker cache is saved to disk. This event can be - * used to add extra content to the cace. + * Triggered before the [general tracker cache](/guides/all-about-tracking#the-tracker-cache) + * is saved to disk. This event can be used to add extra content to the cache. * * Data that is used during tracking but is expensive to compute/query should be - * cached so as not to slow the tracker down. One example of such data are options - * that are stored in the piwik_option table. Requesting data on each tracking - * request means an extra unnecessary database query on each visitor action. + * cached to keep tracking efficient. One example of such data are options + * that are stored in the piwik_option table. Querying data for each tracking + * request means an extra unnecessary database query for each visitor action. Using + * a cache solves this problem. * * **Example** * diff --git a/core/Tracker/GoalManager.php b/core/Tracker/GoalManager.php index b626485ca5..ca385fc59b 100644 --- a/core/Tracker/GoalManager.php +++ b/core/Tracker/GoalManager.php @@ -352,33 +352,33 @@ class GoalManager * Records an Ecommerce conversion in the DB. Deals with Items found in the request. * Will deal with 2 types of conversions: Ecommerce Order and Ecommerce Cart update (Add to cart, Update Cart etc). * - * @param array $goal - * @param array $visitorInformation + * @param array $conversion + * @param array $visitInformation */ - protected function recordEcommerceGoal($goal, $visitorInformation) + protected function recordEcommerceGoal($conversion, $visitInformation) { if ($this->isThereExistingCartInVisit) { Common::printDebug("There is an existing cart for this visit"); } if ($this->isGoalAnOrder) { - $goal['idgoal'] = self::IDGOAL_ORDER; - $goal['idorder'] = $this->orderId; - $goal['buster'] = Common::hashStringToInt($this->orderId); - $goal['revenue_subtotal'] = $this->getRevenue($this->request->getParam('ec_st')); - $goal['revenue_tax'] = $this->getRevenue($this->request->getParam('ec_tx')); - $goal['revenue_shipping'] = $this->getRevenue($this->request->getParam('ec_sh')); - $goal['revenue_discount'] = $this->getRevenue($this->request->getParam('ec_dt')); + $conversion['idgoal'] = self::IDGOAL_ORDER; + $conversion['idorder'] = $this->orderId; + $conversion['buster'] = Common::hashStringToInt($this->orderId); + $conversion['revenue_subtotal'] = $this->getRevenue($this->request->getParam('ec_st')); + $conversion['revenue_tax'] = $this->getRevenue($this->request->getParam('ec_tx')); + $conversion['revenue_shipping'] = $this->getRevenue($this->request->getParam('ec_sh')); + $conversion['revenue_discount'] = $this->getRevenue($this->request->getParam('ec_dt')); $debugMessage = 'The conversion is an Ecommerce order'; } // If Cart update, select current items in the previous Cart else { - $goal['buster'] = 0; - $goal['idgoal'] = self::IDGOAL_CART; + $conversion['buster'] = 0; + $conversion['idgoal'] = self::IDGOAL_CART; $debugMessage = 'The conversion is an Ecommerce Cart Update'; } - $goal['revenue'] = $this->getRevenue($this->request->getGoalRevenue($defaultRevenue = 0)); + $conversion['revenue'] = $this->getRevenue($this->request->getGoalRevenue($defaultRevenue = 0)); - Common::printDebug($debugMessage . ':' . var_export($goal, true)); + Common::printDebug($debugMessage . ':' . var_export($conversion, true)); // INSERT or Sync items in the Cart / Order for this visit & order $items = $this->getEcommerceItemsFromRequest(); @@ -390,29 +390,35 @@ class GoalManager foreach ($items as $item) { $itemsCount += $item[self::INTERNAL_ITEM_QUANTITY]; } - $goal['items'] = $itemsCount; + $conversion['items'] = $itemsCount; if($this->isThereExistingCartInVisit) { $updateWhere = array( - 'idvisit' => $visitorInformation['idvisit'], + 'idvisit' => $visitInformation['idvisit'], 'idgoal' => self::IDGOAL_CART, 'buster' => 0, ); - $recorded = $this->updateExistingConversion($goal, $updateWhere); + $recorded = $this->updateExistingConversion($conversion, $updateWhere); } else { - $recorded = $this->insertNewConversion($goal, $visitorInformation); + $recorded = $this->insertNewConversion($conversion, $visitInformation); } if ($recorded) { - $this->recordEcommerceItems($goal, $items, $visitorInformation); + $this->recordEcommerceItems($conversion, $items, $visitInformation); } /** - * 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`. - * `$visitor` contains the current known visit information. + * Triggered after successfully persisting an ecommerce conversion. + * + * _Note: Subscribers should be wary of doing any expensive computation here as it may slow + * the tracker down._ + * + * @param array $conversion The conversion entity that was just persisted. See what information + * it contains [here](/guides/persistence-and-the-mysql-backend#conversions). + * @param array $visitInformation The visit entity that we are tracking a conversion for. See what + * information it contains [here](/guides/persistence-and-the-mysql-backend#visits). */ - Piwik::postEvent('Tracker.recordEcommerceGoal', array($goal, $visitorInformation)); + Piwik::postEvent('Tracker.recordEcommerceGoal', array($conversion, $visitInformation)); } /** @@ -756,59 +762,67 @@ class GoalManager { foreach ($this->convertedGoals as $convertedGoal) { Common::printDebug("- Goal " . $convertedGoal['idgoal'] . " matched. Recording..."); - $newGoal = $goal; - $newGoal['idgoal'] = $convertedGoal['idgoal']; - $newGoal['url'] = $convertedGoal['url']; - $newGoal['revenue'] = $this->getRevenue($convertedGoal['revenue']); + $conversion = $goal; + $conversion['idgoal'] = $convertedGoal['idgoal']; + $conversion['url'] = $convertedGoal['url']; + $conversion['revenue'] = $this->getRevenue($convertedGoal['revenue']); if (!is_null($action)) { - $newGoal['idaction_url'] = $action->getIdActionUrl(); - $newGoal['idlink_va'] = $action->getIdLinkVisitAction(); + $conversion['idaction_url'] = $action->getIdActionUrl(); + $conversion['idlink_va'] = $action->getIdLinkVisitAction(); } // If multiple Goal conversions per visit, set a cache buster - $newGoal['buster'] = $convertedGoal['allow_multiple'] == 0 + $conversion['buster'] = $convertedGoal['allow_multiple'] == 0 ? '0' : $visitorInformation['visit_last_action_time']; - $this->insertNewConversion($newGoal, $visitorInformation); + $this->insertNewConversion($conversion, $visitorInformation); /** - * 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`. + * Triggered after successfully recording a non-ecommerce conversion. + * + * _Note: Subscribers should be wary of doing any expensive computation here as it may slow + * the tracker down._ + * + * @param array $conversion The conversion entity that was just persisted. See what information + * it contains [here](/guides/persistence-and-the-mysql-backend#conversions). */ - Piwik::postEvent('Tracker.recordStandardGoals', array($newGoal)); + Piwik::postEvent('Tracker.recordStandardGoals', array($conversion)); } } /** * Helper function used by other record* methods which will INSERT or UPDATE the conversion in the DB * - * @param array $newGoal - * @param array $visitorInformation + * @param array $conversion + * @param array $visitInformation * @return bool */ - protected function insertNewConversion($newGoal, $visitorInformation) + protected function insertNewConversion($conversion, $visitInformation) { /** - * This hook is called before inserting a new Goal Conversion.. You can use it to update the Goal - * attributes before they are saved in the log_conversion table. - * `$visitor` contains the current known visit information. - * @param array $goal Array of SQL fields value for this conversion, will be inserted in the log_conversion table - * @param array $visitorInformation Array of log_visit field values for this visitor - * @param \Piwik\Tracker\Request $request + * Triggered before persisting a new [conversion entity](/guides/persistence-and-the-mysql-backend#conversions). + * + * This event can be used to modify conversion information or to add new information to be persisted. + * + * @param array $conversion The conversion entity. Read [this](/guides/persistence-and-the-mysql-backend#conversions) + * to see what it contains. + * @param array $visitInformation The visit entity that we are tracking a conversion for. See what + * information it contains [here](/guides/persistence-and-the-mysql-backend#visits). + * @param \Piwik\Tracker\Request $request An object describing the tracking request being processed. */ - Piwik::postEvent('Tracker.newConversionInformation', array( &$newGoal, $visitorInformation, $this->request)); + Piwik::postEvent('Tracker.newConversionInformation', array(&$conversion, $visitInformation, $this->request)); - $newGoalDebug = $newGoal; + $newGoalDebug = $conversion; $newGoalDebug['idvisitor'] = bin2hex($newGoalDebug['idvisitor']); Common::printDebug($newGoalDebug); - $fields = implode(", ", array_keys($newGoal)); - $bindFields = Common::getSqlStringFieldsArray($newGoal); + $fields = implode(", ", array_keys($conversion)); + $bindFields = Common::getSqlStringFieldsArray($conversion); $sql = 'INSERT IGNORE INTO ' . Common::prefixTable('log_conversion') . " ($fields) VALUES ($bindFields) "; - $bind = array_values($newGoal); + $bind = array_values($conversion); $result = Tracker::getDatabase()->query($sql, $bind); // If a record was inserted, we return true diff --git a/core/Tracker/Referrer.php b/core/Tracker/Referrer.php index 983c969535..402f85d222 100644 --- a/core/Tracker/Referrer.php +++ b/core/Tracker/Referrer.php @@ -135,10 +135,10 @@ class Referrer * - **name**: The search engine name. * - **keywords**: The search keywords used. * - * This parameter will be defaulted to the results + * This parameter is initialized to the results * of Piwik's default search engine detection * logic. - * @param string referrerUrl The referrer URL. + * @param string referrerUrl The referrer URL from the tracking request. */ Piwik::postEvent('Tracker.detectReferrerSearchEngine', array(&$searchEngineInformation, $this->referrerUrl)); if ($searchEngineInformation === false) { diff --git a/core/Tracker/Request.php b/core/Tracker/Request.php index 13f81eab98..c8453dd865 100644 --- a/core/Tracker/Request.php +++ b/core/Tracker/Request.php @@ -304,15 +304,15 @@ class Request $idSite = Common::getRequestVar('idsite', 0, 'int', $this->params); /** - * Triggered when obtaining the ID of the site that is currently being tracked. + * Triggered when obtaining the ID of the site we are tracking a visit for. * - * This event can be used to modify the site ID from what is specified by the **idsite** - * query parameter. + * This event can be used to change the site ID so data is tracked for a different + * website. * * @param int &$idSite Initialized to the value of the **idsite** query parameter. If a * subscriber sets this variable, the value it uses must be greater * than 0. - * @param array $params The entire array of request parameters passed with this tracking + * @param array $params The entire array of request parameters in the current tracking * request. */ Piwik::postEvent('Tracker.Request.getIdSite', array(&$idSite, $this->params)); diff --git a/core/Tracker/Visit.php b/core/Tracker/Visit.php index e5071be6be..962eeb772f 100644 --- a/core/Tracker/Visit.php +++ b/core/Tracker/Visit.php @@ -91,7 +91,12 @@ class Visit implements VisitInterface } /** - * This event can be used for instance to anonymize the IP (after testing for IP exclusion). + * Triggered after visits are tested for exclusion so plugins can modify the IP address + * persisted with a visit. + * + * This event is primarily used by the **AnonymizeIP** plugin to anonymize IP addresses. + * + * @param string &$ip The visitor's IP address. */ Piwik::postEvent('Tracker.setVisitorIp', array(&$this->visitorInfo['location_ip'])); @@ -238,8 +243,15 @@ class Visit implements VisitInterface } /** - * This event is triggered before updating an existing visit's row. Use it to change any visitor information before - * the visitor is saved, or register information about an existing visitor. + * Triggered before a [visit entity](/guides/persistence-and-the-mysql-backend#visits) is updated when + * tracking an action for an existing visit. + * + * This event can be used to modify the visit properties that will be updated before the changes + * are persisted. + * + * @param array &$valuesToUpdate Visit entity properties that will be updated. + * @param array $visit The entire visit entity. Read [this](/guides/persistence-and-the-mysql-backend#visits) + * to see what it contains. */ Piwik::postEvent('Tracker.existingVisitInformation', array(&$valuesToUpdate, $this->visitorInfo)); @@ -286,14 +298,14 @@ class Visit implements VisitInterface $this->visitorInfo['config_resolution'] = substr($this->visitorInfo['config_resolution'], 0, 9); /** - * This event can be used to determine and set new visit information before the visit is - * logged. The UserCountry plugin, for example, uses this event to inject location information - * into the visit log table. + * Triggered before a new [visit entity](/guides/persistence-and-the-mysql-backend#visits) is persisted. + * + * This event can be used to modify the visit entity or add new information to it before it is persisted. + * The UserCountry plugin, for example, uses this event to add location information for each visit. * - * @param array $visitInfo Information regarding the visit. This is information that - * persisted to the database. - * @param \Piwik\Tracker\Request $request Request object, contains many useful methods - * such as getUserAgent() or getIp() to get the original IP. + * @param array &$visit The visit entity. Read [this](/guides/persistence-and-the-mysql-backend#visits) to see + * what information it contains. + * @param \Piwik\Tracker\Request $request An object describing the tracking request being processed. */ Piwik::postEvent('Tracker.newVisitorInformation', array(&$this->visitorInfo, $this->request)); @@ -967,14 +979,25 @@ class Visit implements VisitInterface ); /** - * Use this event to load additional fields from the log_visit table into the visitor array for later use. + * Triggered when checking if the current action being tracked belongs to an existing visit. + * + * This event collects a list of [visit entity]() properties that should be loaded when reading + * the existing visit. Properties that appear in this list will be available in other tracking + * events such as {@hook Tracker.newConversionInformation} and {@hook Tracker.newVisitorInformation}. + * + * Plugins can use this event to load additional visit entity properties for later use during tracking. * When you add fields to this $fields array, they will be later available in Tracker.newConversionInformation - * or Tracker.newVisitorInformation. + * + * **Example** + * + * Piwik::addAction('Tracker.getVisitFieldsToPersist', function (&$fields) { + * $fields[] = 'custom_visit_property'; + * }); + * + * @param array &$fields The list of visit properties to load. */ - Piwik::postEvent('Tracker.getVisitFieldsToPersist', array( &$fields )); + Piwik::postEvent('Tracker.getVisitFieldsToPersist', array(&$fields)); return $fields; - } - -} +}
\ No newline at end of file diff --git a/core/Tracker/VisitExcluded.php b/core/Tracker/VisitExcluded.php index b9506bc46d..d52c4f6561 100644 --- a/core/Tracker/VisitExcluded.php +++ b/core/Tracker/VisitExcluded.php @@ -73,13 +73,13 @@ class VisitExcluded } /** - * Triggered on every pageview of a visitor. + * Triggered on every tracking request. * - * This event can be used to tell the Tracker not to record this particular pageview. + * This event can be used to tell the Tracker not to record this particular action or visit. * - * @param bool &$excluded Whether the pageview should be excluded or not. Initialized + * @param bool &$excluded Whether the request should be excluded or not. Initialized * to `false`. Event subscribers should set it to `true` in - * order to exclude the pageview. + * order to exclude the request. */ Piwik::postEvent('Tracker.isExcludedVisit', array(&$excluded)); diff --git a/core/Translate.php b/core/Translate.php index d66e18a633..27570fb1cc 100644 --- a/core/Translate.php +++ b/core/Translate.php @@ -118,7 +118,7 @@ class Translate * } * } * - * @param string &$lang The language that should be used for the user. Will be + * @param string &$lang The language that should be used for the current user. Will be * initialized to the value of the **language** query parameter. */ Piwik::postEvent('User.getLanguage', array(&$lang)); @@ -177,8 +177,10 @@ class Translate /** * Triggered before generating the JavaScript code that allows i18n strings to be used - * in the browser. Plugins should subscribe to this event to specify which translations - * should be available in JavaScript code. + * in the browser. + * + * Plugins should subscribe to this event to specify which translations + * should be available to JavaScript. * * Event handlers should add whole translation keys, ie, keys that include the plugin name. * diff --git a/core/View/ReportsByDimension.php b/core/View/ReportsByDimension.php index 24f2110475..c3a298f588 100644 --- a/core/View/ReportsByDimension.php +++ b/core/View/ReportsByDimension.php @@ -91,9 +91,12 @@ class ReportsByDimension extends View public function render() { /** - * Use this hook to configure the "Report by dimension" UI controller. This controller is displayed for example - * in the Referrers>Overview and the Goals>Overview report. It displays a list of repotrs on the left, and when click - * loads the report on the right column. This hook can be used to filter this list of report. @see ReportsByDimension class for more info. + * Triggered before rendering {@link ReportsByDimension} views. + * + * Plugins can use this event to configure {@link ReportsByDimension} instances by + * adding or removing reports to display. + * + * @param ReportsByDimension $this The view instance. */ Piwik::postEvent('View.ReportsByDimension.render', array($this)); @@ -125,4 +128,4 @@ class ReportsByDimension extends View return parent::render(); } -} +}
\ No newline at end of file diff --git a/core/ViewDataTable/Factory.php b/core/ViewDataTable/Factory.php index 44b601478f..0a9510372a 100644 --- a/core/ViewDataTable/Factory.php +++ b/core/ViewDataTable/Factory.php @@ -151,18 +151,22 @@ class Factory if (null === self::$defaultViewTypes) { self::$defaultViewTypes = array(); /** - * Triggered when gathering the default view types for all available reports. By default the HtmlTable - * visualization is used. If you define your own report, you may want to subscribe to this event to - * make sure another Visualization is used (for example, a pie graph, bar graph, or something else). + * Triggered when gathering the default view types for all available reports. + * + * If you define your own report, you may want to subscribe to this event to + * make sure the correct default Visualization is used (for example, a pie graph, + * bar graph, or something else). * + * If there is no default type associated with a report, the **table** visualization + * used. + * * **Example** - * ``` - * public function getDefaultTypeViewDataTable(&$defaultViewTypes) - * { - * $defaultViewTypes['Referrers.getSocials'] = HtmlTable::ID; - * $defaultViewTypes['Referrers.getUrlsForSocial'] = Pie::ID; - * } - * ``` + * + * public function getDefaultTypeViewDataTable(&$defaultViewTypes) + * { + * $defaultViewTypes['Referrers.getSocials'] = HtmlTable::ID; + * $defaultViewTypes['Referrers.getUrlsForSocial'] = Pie::ID; + * } * * @param array &$defaultViewTypes The array mapping report IDs with visualization IDs. */ diff --git a/core/WidgetsList.php b/core/WidgetsList.php index 26b4086d83..a3b1098940 100644 --- a/core/WidgetsList.php +++ b/core/WidgetsList.php @@ -74,7 +74,7 @@ class WidgetsList self::$hookCalled = true; /** - * Triggered once when the widget list is first requested. Collects all available widgets. + * Used to collect all available dashboard widgets. * * Subscribe to this event to make your plugin's reports or other controller actions available * as dashboard widgets. Event handlers should call the {@link WidgetsList::add()} method for each @@ -82,12 +82,10 @@ class WidgetsList * * **Example** * - * ``` - * public function addWidgets() - * { - * WidgetsList::add('General_Actions', 'General_Pages', 'Actions', 'getPageUrls'); - * } - * ``` + * public function addWidgets() + * { + * WidgetsList::add('General_Actions', 'General_Pages', 'Actions', 'getPageUrls'); + * } */ Piwik::postEvent('WidgetsList.addWidgets'); } diff --git a/plugins/API/API.php b/plugins/API/API.php index 34364dd184..4fdc53f0bb 100644 --- a/plugins/API/API.php +++ b/plugins/API/API.php @@ -85,9 +85,9 @@ class API extends \Piwik\Plugin\API $segments = array(); /** - * Triggered when gathering all available segments. + * Triggered when gathering all available segment dimensions. * - * This event can be used to make new segments available. + * This event can be used to make new segment dimensions available. * * **Example** * @@ -95,7 +95,7 @@ class API extends \Piwik\Plugin\API * { * $segments[] = array( * 'type' => 'dimension', - * 'category' => Piwik::translate('General_Visit'), + * 'category' => Piwik::translate('General_Visit'), * 'name' => 'General_VisitorIP', * 'segment' => 'visitIp', * 'acceptedValues' => '13.54.122.1, etc.', @@ -105,27 +105,27 @@ class API extends \Piwik\Plugin\API * ); * } * - * @param array &$segments The list of available segments. Append to this list to add - * new segments. Each element in this list must contain the - * following information: + * @param array &$dimensions The list of available segment dimensions. Append to this list to add + * new segments. Each element in this list must contain the + * following information: * - * - **type**: Either `'metric'` or `'dimension'`. `'metric'` means - * the value is a numeric and `'dimension'` means it is - * a string. Also, `'metric'` values will be displayed - * **Visit (metrics)** in the Segment Editor. - * - **category**: The segment category name. This can be an existing - * segment category visible in the segment editor. - * - **name**: The pretty name of the segment. - * - **segment**: The segment name, eg, `'visitIp'` or `'searches'`. - * - **acceptedValues**: A string describing one or two exacmple values, eg - * `'13.54.122.1, etc.'`. - * - **sqlSegment**: The table column this segment will segment by. - * For example, `'log_visit.location_ip'` for the - * **visitIp** segment. - * - **sqlFilter**: A PHP callback to apply to segment values before - * they are used in SQL. - * - **permission**: True if the current user has view access to this - * segment, false if otherwise. + * - **type**: Either `'metric'` or `'dimension'`. `'metric'` means + * the value is a numeric and `'dimension'` means it is + * a string. Also, `'metric'` values will be displayed + * under **Visit (metrics)** in the Segment Editor. + * - **category**: The segment category name. This can be an existing + * segment category visible in the segment editor. + * - **name**: The pretty name of the segment. Can be a translation token. + * - **segment**: The segment name, eg, `'visitIp'` or `'searches'`. + * - **acceptedValues**: A string describing one or two exacmple values, eg + * `'13.54.122.1, etc.'`. + * - **sqlSegment**: The table column this segment will segment by. + * For example, `'log_visit.location_ip'` for the + * **visitIp** segment. + * - **sqlFilter**: A PHP callback to apply to segment values before + * they are used in SQL. + * - **permission**: True if the current user has view access to this + * segment, false if otherwise. * @param array $idSites The list of site IDs we're getting the available segments * for. Some segments (such as Goal segments) depend on the * site. diff --git a/plugins/API/ProcessedReport.php b/plugins/API/ProcessedReport.php index 79fca329c0..910623a858 100644 --- a/plugins/API/ProcessedReport.php +++ b/plugins/API/ProcessedReport.php @@ -87,27 +87,49 @@ class ProcessedReport $availableReports = array(); /** - * Triggered when gathering the metadata for all available reports. + * Triggered when gathering metadata for all available reports. * * Plugins that define new reports should use this event to make them available in via * the metadata API. By doing so, the report will become available in scheduled reports * as well as in the Piwik Mobile App. In fact, any third party app that uses the metadata * API will automatically have access to the new report. * - * TODO: list all information that is required in $availableReports. - * * @param string &$availableReports The list of available reports. Append to this list * to make a report available. + * + * Every element of this array must contain the following + * information: + * + * - **category**: A translated string describing the report's category. + * - **name**: The translated display title of the report. + * - **module**: The plugin of the report. + * - **action**: The API method that serves the report. + * + * The following information is optional: + * + * - **dimension**: The report's [dimension](/guides/all-about-analytics-data#dimensions) if any. + * - **metrics**: An array mapping metric names with their display names. + * - **metricsDocumentation**: An array mapping metric names with their + * translated documentation. + * - **processedMetrics**: The array of metrics in the report that are + * calculated using existing metrics. Can be set to + * `false` if the report contains no processed + * metrics. + * - **order**: The order of the report in the list of reports + * with the same category. + * * @param array $parameters Contains the values of the sites and period we are - * getting reports for. Some report depend on this data. + * getting reports for. Some reports depend on this data. * For example, Goals reports depend on the site IDs being - * request. Contains the following information: + * requested. Contains the following information: * * - **idSites**: The array of site IDs we are getting reports for. * - **period**: The period type, eg, `'day'`, `'week'`, `'month'`, * `'year'`, `'range'`. * - **date**: A string date within the period or a date range, eg, * `'2013-01-01'` or `'2012-01-01,2013-01-01'`. + * + * TODO: put dimensions section in all about analytics data */ Piwik::postEvent('API.getReportMetadata', array(&$availableReports, $parameters)); foreach ($availableReports as &$availableReport) { @@ -134,7 +156,8 @@ class ProcessedReport * could, for example, add custom metrics to every report or remove reports from the list * of available reports. * - * @param array &$availableReports List of all report metadata. + * @param array &$availableReports List of all report metadata. Read the {@hook API.getReportMetadata} + * docs to see what this array contains. * @param array $parameters Contains the values of the sites and period we are * getting reports for. Some report depend on this data. * For example, Goals reports depend on the site IDs being diff --git a/plugins/Goals/Goals.php b/plugins/Goals/Goals.php index 9f63cd39dc..5a5de35886 100644 --- a/plugins/Goals/Goals.php +++ b/plugins/Goals/Goals.php @@ -364,14 +364,31 @@ class Goals extends \Piwik\Plugin /** * Triggered when gathering all reports that contain Goal metrics. The list of reports - * will be displayed on the left column of the bottom of the Goals Overview page and - * each individual Goal page. + * will be displayed on the left column of the bottom of every _Goals_ page. * - * If plugins define reports that contain Goal metrics (such as conversions or revenue), - * they can use this event to make sure their reports can be loaded on the relevant - * Goals pages. + * If plugins define reports that contain goal metrics (such as **conversions** or **revenue**), + * they can use this event to make sure their reports can be viewed on Goals pages. * - * @param array &$reportsWithGoals The list of reports that have Goal metrics. + * **Example** + * + * public function getReportsWithGoalMetrics(&$reports) + * { + * $reports[] = array( + * 'category' => Piwik::translate('MyPlugin_myReportCategory'), + * 'name' => Piwik::translate('MyPlugin_myReportDimension'), + * 'module' => 'MyPlugin', + * 'action' => 'getMyReport' + * ); + * } + * + * @param array &$reportsWithGoals The list of arrays describing reports that have Goal metrics. + * Each element of this array must be an array with the following + * properties: + * + * - **category**: The report category. This should be a translated string. + * - **name**: The report's translated name. + * - **module**: The plugin the report is in, eg, `'UserCountry'`. + * - **action**: The API method of the report, eg, `'getCountry'`. */ Piwik::postEvent('Goals.getReportsWithGoalMetrics', array(&$reportsWithGoals)); diff --git a/plugins/Live/API.php b/plugins/Live/API.php index 5d0c685fb3..e80145b563 100644 --- a/plugins/Live/API.php +++ b/plugins/Live/API.php @@ -380,7 +380,7 @@ class API extends \Piwik\Plugin\API * - **visitorAvatar**: A URL to an image to display in the top left corner of the popup. * - **visitorDescription**: Text to be used as the tooltip of the avatar image. * - * @param array &$visitorProfile The normal visitor profile info. + * @param array &$visitorProfile The unaugmented visitor profile info. */ Piwik::postEvent('Live.getExtraVisitorDetails', array(&$result)); diff --git a/plugins/Overlay/API.php b/plugins/Overlay/API.php index 8fd8f26a0b..cd6e4f6754 100644 --- a/plugins/Overlay/API.php +++ b/plugins/Overlay/API.php @@ -107,7 +107,7 @@ class API extends \Piwik\Plugin\API private function authenticate($idSite) { /** - * Triggered shortly before the user is authenticated. + * Triggered immediately before the user is authenticated. * * This event can be used by plugins that provide their own authentication mechanism * to make that mechanism available. Subscribers should set the `'auth'` object in @@ -122,7 +122,7 @@ class API extends \Piwik\Plugin\API * Registry::set('auth', new LDAPAuth($allowCookieAuthentication)); * } * - * @param bool $allowCookieAuthentication Whether authentication based on $_COOKIE values should + * @param bool $allowCookieAuthentication Whether authentication based on `$_COOKIE` values should * be allowed. */ Piwik::postEvent('Request.initAuthenticationObject', array($allowCookieAuthentication = true)); diff --git a/plugins/Provider/Provider.php b/plugins/Provider/Provider.php index 52cfd4105f..cab6221343 100644 --- a/plugins/Provider/Provider.php +++ b/plugins/Provider/Provider.php @@ -166,21 +166,23 @@ class Provider extends \Piwik\Plugin $cleanHostname = null; /** - * Triggered when prettifying a hostname string. depending on a given hostname. + * Triggered when prettifying a hostname string. * * This event can be used to customize the way a hostname is displayed in the * Providers report. * * **Example** * - * ``` - * public function getCleanHostname(&$cleanHostname, $hostname) - * { - * if ('fvae.VARG.ceaga.site.co.jp' == $hostname) { - * $cleanHostname = 'site.co.jp'; + * public function getCleanHostname(&$cleanHostname, $hostname) + * { + * if ('fvae.VARG.ceaga.site.co.jp' == $hostname) { + * $cleanHostname = 'site.co.jp'; + * } * } - * } - * ``` + * + * @param string &$cleanHostname The hostname string to display. Set by the event + * handler. + * @param string $hostname The full hostname. */ Piwik::postEvent('Provider.getCleanHostname', array(&$cleanHostname, $hostname)); if ($cleanHostname !== null) { diff --git a/plugins/ScheduledReports/API.php b/plugins/ScheduledReports/API.php index bb4bcd9b79..4970c0593a 100644 --- a/plugins/ScheduledReports/API.php +++ b/plugins/ScheduledReports/API.php @@ -386,16 +386,15 @@ class API extends \Piwik\Plugin\API /** * Triggered when generating the content of scheduled reports. * - * This event can be used to modify the content of processed report data or - * metadata, either for one specific report/report type/output format or all - * of them. + * This event can be used to modify the report data or report metadata of one or more reports + * in a scheduled report, before the scheduled report is rendered and delivered. * * TODO: list data available in $report or make it a new class that can be documented (same for * all other events that use a $report) * * @param array &$processedReports The list of processed reports in the scheduled - * report. Includes report data and metadata. - * @param string $reportType A string ID describing how the report is sent, eg, + * report. Entries includes report data and metadata for each report. + * @param string $reportType A string ID describing how the scheduled report will be sent, eg, * `'sms'` or `'email'`. * @param string $outputType The output format of the report, eg, `'html'`, `'pdf'`, etc. * @param array $report An array describing the scheduled report that is being @@ -409,10 +408,10 @@ class API extends \Piwik\Plugin\API $reportRenderer = null; /** - * Triggered when obtaining a renderer instance based on the scheduled report type. + * Triggered when obtaining a renderer instance based on the scheduled report output format. * - * Plugins that provide new scheduled report backends should use this event to - * handle their new report types. + * Plugins that provide new scheduled report output formats should use this event to + * handle their new report formats. * * @param ReportRenderer &$reportRenderer This variable should be set to an instance that * extends {@link Piwik\ReportRenderer} by one of the event @@ -523,8 +522,8 @@ class API extends \Piwik\Plugin\API /** * Triggered when sending scheduled reports. * - * Plugins that provide new scheduled report backends should use this event to - * send the scheduled report uses their backend. + * Plugins that provide new scheduled report transport mediums should use this event to + * send the scheduled report. * * @param string $reportType A string ID describing how the report is sent, eg, * `'sms'` or `'email'`. @@ -538,7 +537,7 @@ class API extends \Piwik\Plugin\API * scheduled report. * @param string $reportSubject A string describing what's in the scheduled * report. - * @param string $reportTitle The scheduled report's given title. + * @param string $reportTitle The scheduled report's given title (given by a Piwik user). * @param array $additionalFiles The list of additional files that should be * sent with this report. */ @@ -591,8 +590,8 @@ class API extends \Piwik\Plugin\API /** * Triggered when gathering the available parameters for a scheduled report type. * - * Plugins that provide their own scheduled reports backend should use this - * event to list the available report parameters for their backend. + * Plugins that provide their own scheduled report transport mediums should use this + * event to list the available report parameters for their transport medium. * * @param array $availableParameters The list of available parameters for this report type. * This is an array that maps paramater IDs with a boolean @@ -733,13 +732,15 @@ class API extends \Piwik\Plugin\API $availableReportMetadata = array(); /** + * TODO: change this event so it returns a list of API methods instead of report metadata arrays. * Triggered when gathering the list of Piwik reports that can be used with a certain - * scheduled reports backend. + * transport medium. * - * Plugins that provide their own scheduled reports backend should use this + * Plugins that provide their own transport mediums should use this * event to list the Piwik reports that their backend supports. * - * @param array &$availableReportMetadata + * @param array &$availableReportMetadata An array containg report metadata for each supported + * report. * @param string $reportType A string ID describing how the report is sent, eg, * `'sms'` or `'email'`. * @param int $idSite The ID of the site we're getting available reports for. @@ -760,10 +761,10 @@ class API extends \Piwik\Plugin\API $allowMultipleReports = null; /** - * Triggered when we're determining if a scheduled report backend can + * Triggered when we're determining if a scheduled report transport medium can * handle sending multiple Piwik reports in one scheduled report or not. * - * Plugins that provide their own scheduled reports backend should use this + * Plugins that provide their own transport mediums should use this * event to specify whether their backend can send more than one Piwik report * at a time. * @@ -787,14 +788,13 @@ class API extends \Piwik\Plugin\API $reportTypes = array(); /** - * Triggered when gathering all available scheduled report backend types. + * Triggered when gathering all available transport mediums. * - * Plugins that provide their own scheduled reports backend should use this - * event to make their backend available. + * Plugins that provide their own transport mediums should use this + * event to make their medium available. * - * @param array &$reportTypes An array mapping string IDs for each available - * scheduled report backend with icon paths for those - * backends. Add your new backend's ID to this array. + * @param array &$reportTypes An array mapping transport medium IDs with the paths to those + * mediums' icons. Add your new backend's ID to this array. */ Piwik::postEvent(self::GET_REPORT_TYPES_EVENT, array(&$reportTypes)); @@ -817,6 +817,8 @@ class API extends \Piwik\Plugin\API * @param array &$reportFormats An array mapping string IDs for each available * scheduled report format with icon paths for those * formats. Add your new format's ID to this array. + * @param string $reportType A string ID describing how the report is sent, eg, + * `'sms'` or `'email'`. */ Piwik::postEvent( self::GET_REPORT_FORMATS_EVENT, @@ -836,8 +838,8 @@ class API extends \Piwik\Plugin\API /** * Triggered when getting the list of recipients of a scheduled report. * - * Plugins that provide their own scheduled report backend should use this event - * so the list of recipients can be extracted from their backend's specific report + * Plugins that provide their own scheduled report transport medium should use this event + * to extract the list of recipients their backend's specific scheduled report * format. * * @param array &$recipients An array of strings describing each of the scheduled @@ -936,4 +938,4 @@ class API extends \Piwik\Plugin\API return $additionalFile; } -} +}
\ No newline at end of file diff --git a/plugins/UsersManager/API.php b/plugins/UsersManager/API.php index a1beb26f0b..2d713b225d 100644 --- a/plugins/UsersManager/API.php +++ b/plugins/UsersManager/API.php @@ -653,8 +653,8 @@ class API extends \Piwik\Plugin\API /** * Triggered after a user has been deleted. * - * This event should be used to clean up any data that is related to the user that was - * deleted. For example, the Dashboard plugin uses this event to remove the user's dashboards. + * This event should be used to clean up any data that is related to the now deleted user. + * The **Dashboard** plugin, for example, uses this event to remove the user's dashboards. * * @param string $userLogin The login handle of the deleted user. */ diff --git a/tests/PHPUnit/UI b/tests/PHPUnit/UI -Subproject 4df88a1f66a102521cf5ec459b90be780f2c351 +Subproject 673d21c6a750d8280f4e9ab9d203072dd8d844d |