From 055eaa81b651c4839d9061311a7e93ceb195c7ed Mon Sep 17 00:00:00 2001 From: diosmosis Date: Mon, 21 Oct 2013 05:03:14 -0400 Subject: Refs #4200 documented core/API/Request.php and part of core/DataTable/Simple.php --- core/API/Request.php | 129 ++++++++++++++++++++++++++++++---------------- core/ArchiveProcessor.php | 2 +- core/DataTable/Simple.php | 18 +++---- 3 files changed, 93 insertions(+), 56 deletions(-) diff --git a/core/API/Request.php b/core/API/Request.php index ae61f97082..8d183f3834 100644 --- a/core/API/Request.php +++ b/core/API/Request.php @@ -22,26 +22,39 @@ use Piwik\Url; use Piwik\UrlHelper; /** - * An API request is the object used to make a call to the API and get the result. - * The request has the format of a normal GET request, ie. parameter_1=X¶meter_2=Y + * Dispatches API requests to the appropriate API method. + * + * The Request class is used throughout Piwik to call API methods. The difference + * between using Request and calling API methods directly is that Request + * will do more after calling the API including: apply generic filters, apply queued filters, + * and handle the **flat** and **label** query parameters. + * + * Additionally, the Request class will **forward current query parameters** to the request + * which is more convenient than calling [Common::getRequestVar](#) many times over. + * + * In most cases, using a Request object to query the API is the right way to go. * - * You can use this object from anywhere in piwik (inside plugins for example). - * You can even call it outside of piwik using the REST API over http - * or in a php script on the same server as piwik, by including piwik/index.php - * (see examples in the documentation http://piwik.org/docs/analytics-api) - * - * Example: - * $request = new Request(' - * method=UserSettings.getWideScreen - * &idSite=1 - * &date=yesterday - * &period=week - * &format=xml - * &filter_limit=5 - * &filter_offset=0 - * '); - * $result = $request->process(); - * echo $result; + * ### Examples + * + * **Basic Usage** + * + * $request = new Request('method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week' + * . '&format=xml&filter_limit=5&filter_offset=0') + * $result = $request->process(); + * echo $result; + * + * **Getting a unrendered DataTable** + * + * // use convenience the convenience method 'processRequest' + * $dataTable = Request::processRequest('UserSettings.getWideScreen', array( + * 'idSite' => 1, + * 'date' => 'yesterday', + * 'period' => 'week', + * 'format' => 'original', // this is the important bit + * 'filter_limit' => 5, + * 'filter_offset' => 0 + * )); + * echo "This DataTable has " . $dataTable->getRowsCount() . " rows."; * * @see http://piwik.org/docs/analytics-api * @package Piwik @@ -54,10 +67,13 @@ class Request protected $request = null; /** - * Returns the request array as string + * Converts the supplied request string into an array of query paramater name/value + * mappings. The current query parameters (everything in `$_GET` and `$_POST`) are + * forwarded to request array before it is returned. * - * @param string|array $request - * @return array|null + * @param string|array $request The base request string or array, eg, + * `'module=UserSettings&action=getWidescreen'`. + * @return array */ static public function getRequestArrayFromString($request) { @@ -95,14 +111,14 @@ class Request } /** - * Constructs the request to the API, given the request url + * Constructor. * - * @param string $request GET request that defines the API call (must at least contain a "method" parameter) - * Example: method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week&format=xml - * If a request is not provided, then we use the $_GET and $_POST superglobal and fetch - * the values directly from the HTTP GET query. + * @param string $request GET request that defines the API call (must at least contain a **method** parameter), + * eg, `'method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week&format=xml'` + * If a request is not provided, then we use the $_GET and $_POST superglobal and fetch + * the values directly from the HTTP GET query. */ - function __construct($request = null) + public function __construct($request = null) { $this->request = self::getRequestArrayFromString($request); $this->sanitizeRequest(); @@ -114,6 +130,7 @@ class Request * * @param $module * @return string + * @ignore */ public static function renameModule($module) { @@ -144,13 +161,23 @@ class Request } /** - * Handles the request to the API. - * It first checks that the method called (parameter 'method') is available in the module (it means that the method exists and is public) - * It then reads the parameters from the request string and throws an exception if there are missing parameters. - * It then calls the API Proxy which will call the requested method. - * - * @throws PluginDeactivatedException - * @return DataTable|mixed The data resulting from the API call + * Dispatches the API request to the appropriate API method and returns the result + * after post-processing. + * + * Post-processing includes: + * + * - flattening if **flat** is 0 + * - running generic filters unless **disable_generic_filters** is set to 1 + * - URL decoding label column values + * - running queued filters unless **disable_queued_filters** is set to 1 + * - removes columns based on the values of the **hideColumns** and **showColumns** query parameters + * - filters rows if the **label** query parameter is set + * + * @throws PluginDeactivatedException if the module plugin is not activated. + * @throws Exception if the requested API method cannot be called, if required parameters for the + * API method are missing or if the API method throws an exception and the **format** + * query parameter is **original**. + * @return DataTable|Map|string The data resulting from the API call. */ public function process() { @@ -185,9 +212,15 @@ class Request return $toReturn; } - static public function getClassNameAPI($module) + /** + * Returns the class name of a plugin's API given the plugin name. + * + * @param string $plugin The plugin name. + * @return string + */ + static public function getClassNameAPI($plugin) { - return sprintf('\Piwik\Plugins\%s\API', $module); + return sprintf('\Piwik\Plugins\%s\API', $plugin); } /** @@ -197,6 +230,7 @@ class Request * * @param array $request If null, uses the default request ($_GET) * @return void + * @ignore */ static public function reloadAuthUsingTokenAuth($request = null) { @@ -231,7 +265,8 @@ class Request } /** - * Helper method to process an API request using the variables in $_GET and $_POST. + * Helper method that processes an API request in one line using the variables in `$_GET` + * and `$_POST`. * * @param string $method The API method to call, ie, Actions.getPageTitles * @param array $paramOverride The parameter name-value pairs to use instead of what's @@ -252,6 +287,10 @@ class Request } /** + * Returns the original request parameters in the current query string as an array mapping + * query parameter names with values. This result of this function will not be affected + * by any modifications to `$_GET` and will not include parameters in `$_POST`. + * * @return array */ public static function getRequestParametersGET() @@ -264,12 +303,11 @@ class Request } /** - * Returns URL for this report w/o any filter parameters. - * - * @param string $module - * @param string $action - * @param array $queryParams + * Returns URL for the current requested report w/o any filter parameters. * + * @param string $module The API module. + * @param string $action The API action. + * @param array $queryParams Query parameter overrides. * @return string */ public static function getBaseReportUrl($module, $action, $queryParams = array()) @@ -305,6 +343,7 @@ class Request * current request before rendering. * * @return bool + * @ignore */ public static function shouldLoadExpanded() { @@ -316,6 +355,8 @@ class Request } /** + * Returns the unmodified segment from the original request. + * * @return array|bool */ static public function getRawSegmentFromRequest() @@ -331,4 +372,4 @@ class Request } return $segmentRaw; } -} +} \ No newline at end of file diff --git a/core/ArchiveProcessor.php b/core/ArchiveProcessor.php index 2d9b9b5774..1ff1fd6e9b 100644 --- a/core/ArchiveProcessor.php +++ b/core/ArchiveProcessor.php @@ -453,4 +453,4 @@ abstract class ArchiveProcessor { return $this->requestedPlugin; } -} +} \ No newline at end of file diff --git a/core/DataTable/Simple.php b/core/DataTable/Simple.php index 1a9341221f..e9b2e4e893 100644 --- a/core/DataTable/Simple.php +++ b/core/DataTable/Simple.php @@ -13,14 +13,10 @@ namespace Piwik\DataTable; use Piwik\DataTable; /** - * The DataTable\Simple is used to provide an easy way to create simple DataGrid. - * A DataTable\Simple is a DataTable with 2 columns: 'label' and 'value'. - * - * It is usually best to return a DataTable\Simple instead of - * a PHP array (or other custom data structure) in API methods: - * - the generic filters can be applied automatically (offset, limit, pattern search, sort, etc.) - * - the renderer can be applied (XML, PHP, HTML, etc.) - * So you don't have to write specific renderer for your data, it is already available in all the formats supported natively by Piwik. + * A [DataTable](#) where every row has two columns: **label** and **value**. + * + * Simple DataTables are only used to slightly alter the output of some renderers + * (namely the XML renderer). * * @package Piwik * @subpackage DataTable @@ -28,12 +24,12 @@ use Piwik\DataTable; class Simple extends DataTable { /** - * Loads (append) in the DataTable the array information + * Adds in the DataTable the array information * * @param array $array Array containing the rows information * array( - * 'Label row 1' => Value row 1, - * 'Label row 2' => Value row 2, + * 'Label row 1' => $value1, + * 'Label row 2' => $value2, * ) */ public function addRowsFromArray($array) -- cgit v1.2.3