Skip to content

Commit

Permalink
Fixes #4199, revising event docs and closing ticket.
Browse files Browse the repository at this point in the history
  • Loading branch information
diosmosis committed Dec 5, 2013
1 parent b6c2cf9 commit 777ca60
Show file tree
Hide file tree
Showing 36 changed files with 545 additions and 364 deletions.
89 changes: 68 additions & 21 deletions core/API/Proxy.php
View file
Expand Up @@ -168,27 +168,40 @@ public function call($className, $methodName, $parametersRequest)
/**
* 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.
Expand All @@ -207,21 +220,36 @@ public function call($className, $methodName, $parametersRequest)
);

/**
* 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.
Expand All @@ -235,14 +263,33 @@ public function call($className, $methodName, $parametersRequest)
*
* 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.
Expand Down
4 changes: 2 additions & 2 deletions core/API/Request.php
View file
Expand Up @@ -238,11 +238,11 @@ static public function reloadAuthUsingTokenAuth($request = null)
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.
Expand Down
5 changes: 3 additions & 2 deletions core/Access.php
View file
Expand Up @@ -427,11 +427,12 @@ protected function getIdSites($idSites)
}

/**
* 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
{
}
}
2 changes: 1 addition & 1 deletion core/ArchiveProcessor/Parameters.php
View file
Expand Up @@ -101,7 +101,7 @@ public function getIdSites()

$idSites = array($idSite);

Piwik::postEvent('ArchiveProcessor.Parameters.getIdSites', array( &$idSites, $this->getPeriod() ) );
Piwik::postEvent('ArchiveProcessor.Parameters.getIdSites', array(&$idSites, $this->getPeriod()));

return $idSites;
}
Expand Down
28 changes: 14 additions & 14 deletions core/AssetManager.php
View file
Expand Up @@ -163,7 +163,7 @@ private static function prepareMergedCssFile()
*
* 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));

Expand Down Expand Up @@ -295,12 +295,12 @@ private static function getStylesheetFiles()
* 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**
*
Expand Down Expand Up @@ -382,7 +382,7 @@ private static function generateMergedJsFile()
$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
Expand Down Expand Up @@ -431,19 +431,19 @@ private static function getJsFiles()
* 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.
Expand Down Expand Up @@ -710,4 +710,4 @@ private static function getFirstLineOfMergedJs()
{
return "/* Piwik Javascript - cb=" . self::generateAssetsCacheBuster() . "*/\n";
}
}
}
15 changes: 7 additions & 8 deletions core/Console.php
View file
Expand Up @@ -48,18 +48,17 @@ private function getAvailableCommands()
$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));

Expand Down
9 changes: 7 additions & 2 deletions core/CronArchive.php
View file
Expand Up @@ -795,8 +795,13 @@ private function filterWebsiteIds(&$websiteIds)
$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));
}
Expand Down
24 changes: 12 additions & 12 deletions core/Db.php
View file
Expand Up @@ -74,21 +74,21 @@ public static function createDatabaseObject($dbInfos = null)
}

/**
* 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));

Expand Down

0 comments on commit 777ca60

Please sign in to comment.