Skip to content
Extraits de code Groupes Projets
Valider 055eaa81 rédigé par diosmosis's avatar diosmosis
Parcourir les fichiers

Refs #4200 documented core/API/Request.php and part of core/DataTable/Simple.php

parent 4c212e16
Aucune branche associée trouvée
Aucune étiquette associée trouvée
Aucune requête de fusion associée trouvée
Masquer les modifications d'espaces
En ligne Côte à côte
core/API/Request.php
+ 85
− 44
Voir le fichier @ 055eaa81
...@@ -22,26 +22,39 @@ use Piwik\Url; ...@@ -22,26 +22,39 @@ use Piwik\Url;
use Piwik\UrlHelper; use Piwik\UrlHelper;
/** /**
* An API request is the object used to make a call to the API and get the result. * Dispatches API requests to the appropriate API method.
* The request has the format of a normal GET request, ie. parameter_1=X&parameter_2=Y *
* 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). * ### Examples
* 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 * **Basic Usage**
* (see examples in the documentation http://piwik.org/docs/analytics-api) *
* * $request = new Request('method=UserSettings.getWideScreen&idSite=1&date=yesterday&period=week'
* Example: * . '&format=xml&filter_limit=5&filter_offset=0')
* $request = new Request(' * $result = $request->process();
* method=UserSettings.getWideScreen * echo $result;
* &idSite=1 *
* &date=yesterday * **Getting a unrendered DataTable**
* &period=week *
* &format=xml * // use convenience the convenience method 'processRequest'
* &filter_limit=5 * $dataTable = Request::processRequest('UserSettings.getWideScreen', array(
* &filter_offset=0 * 'idSite' => 1,
* '); * 'date' => 'yesterday',
* $result = $request->process(); * 'period' => 'week',
* echo $result; * '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 * @see http://piwik.org/docs/analytics-api
* @package Piwik * @package Piwik
...@@ -54,10 +67,13 @@ class Request ...@@ -54,10 +67,13 @@ class Request
protected $request = null; 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 * @param string|array $request The base request string or array, eg,
* @return array|null * `'module=UserSettings&action=getWidescreen'`.
* @return array
*/ */
static public function getRequestArrayFromString($request) static public function getRequestArrayFromString($request)
{ {
...@@ -95,14 +111,14 @@ class 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) * @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 * 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 * If a request is not provided, then we use the $_GET and $_POST superglobal and fetch
* the values directly from the HTTP GET query. * the values directly from the HTTP GET query.
*/ */
function __construct($request = null) public function __construct($request = null)
{ {
$this->request = self::getRequestArrayFromString($request); $this->request = self::getRequestArrayFromString($request);
$this->sanitizeRequest(); $this->sanitizeRequest();
...@@ -114,6 +130,7 @@ class Request ...@@ -114,6 +130,7 @@ class Request
* *
* @param $module * @param $module
* @return string * @return string
* @ignore
*/ */
public static function renameModule($module) public static function renameModule($module)
{ {
...@@ -144,13 +161,23 @@ class Request ...@@ -144,13 +161,23 @@ class Request
} }
/** /**
* Handles the request to the API. * Dispatches the API request to the appropriate API method and returns the result
* It first checks that the method called (parameter 'method') is available in the module (it means that the method exists and is public) * after post-processing.
* 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. * Post-processing includes:
* *
* @throws PluginDeactivatedException * - flattening if **flat** is 0
* @return DataTable|mixed The data resulting from the API call * - 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() public function process()
{ {
...@@ -185,9 +212,15 @@ class Request ...@@ -185,9 +212,15 @@ class Request
return $toReturn; 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 ...@@ -197,6 +230,7 @@ class Request
* *
* @param array $request If null, uses the default request ($_GET) * @param array $request If null, uses the default request ($_GET)
* @return void * @return void
* @ignore
*/ */
static public function reloadAuthUsingTokenAuth($request = null) static public function reloadAuthUsingTokenAuth($request = null)
{ {
...@@ -231,7 +265,8 @@ class Request ...@@ -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 string $method The API method to call, ie, Actions.getPageTitles
* @param array $paramOverride The parameter name-value pairs to use instead of what's * @param array $paramOverride The parameter name-value pairs to use instead of what's
...@@ -252,6 +287,10 @@ class Request ...@@ -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 * @return array
*/ */
public static function getRequestParametersGET() public static function getRequestParametersGET()
...@@ -264,12 +303,11 @@ class Request ...@@ -264,12 +303,11 @@ class Request
} }
/** /**
* Returns URL for this report w/o any filter parameters. * Returns URL for the current requested report w/o any filter parameters.
*
* @param string $module
* @param string $action
* @param array $queryParams
* *
* @param string $module The API module.
* @param string $action The API action.
* @param array $queryParams Query parameter overrides.
* @return string * @return string
*/ */
public static function getBaseReportUrl($module, $action, $queryParams = array()) public static function getBaseReportUrl($module, $action, $queryParams = array())
...@@ -305,6 +343,7 @@ class Request ...@@ -305,6 +343,7 @@ class Request
* current request before rendering. * current request before rendering.
* *
* @return bool * @return bool
* @ignore
*/ */
public static function shouldLoadExpanded() public static function shouldLoadExpanded()
{ {
...@@ -316,6 +355,8 @@ class Request ...@@ -316,6 +355,8 @@ class Request
} }
/** /**
* Returns the unmodified segment from the original request.
*
* @return array|bool * @return array|bool
*/ */
static public function getRawSegmentFromRequest() static public function getRawSegmentFromRequest()
...@@ -331,4 +372,4 @@ class Request ...@@ -331,4 +372,4 @@ class Request
} }
return $segmentRaw; return $segmentRaw;
} }
} }
\ No newline at end of file
core/ArchiveProcessor.php
+ 1
− 1
Voir le fichier @ 055eaa81
...@@ -453,4 +453,4 @@ abstract class ArchiveProcessor ...@@ -453,4 +453,4 @@ abstract class ArchiveProcessor
{ {
return $this->requestedPlugin; return $this->requestedPlugin;
} }
} }
\ No newline at end of file
core/DataTable/Simple.php
+ 7
− 11
Voir le fichier @ 055eaa81
...@@ -13,14 +13,10 @@ namespace Piwik\DataTable; ...@@ -13,14 +13,10 @@ namespace Piwik\DataTable;
use Piwik\DataTable; use Piwik\DataTable;
/** /**
* The DataTable\Simple is used to provide an easy way to create simple DataGrid. * A [DataTable](#) where every row has two columns: **label** and **value**.
* A DataTable\Simple is a DataTable with 2 columns: 'label' and 'value'. *
* * Simple DataTables are only used to slightly alter the output of some renderers
* It is usually best to return a DataTable\Simple instead of * (namely the XML renderer).
* 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.
* *
* @package Piwik * @package Piwik
* @subpackage DataTable * @subpackage DataTable
...@@ -28,12 +24,12 @@ use Piwik\DataTable; ...@@ -28,12 +24,12 @@ use Piwik\DataTable;
class Simple extends 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 * @param array $array Array containing the rows information
* array( * array(
* 'Label row 1' => Value row 1, * 'Label row 1' => $value1,
* 'Label row 2' => Value row 2, * 'Label row 2' => $value2,
* ) * )
*/ */
public function addRowsFromArray($array) public function addRowsFromArray($array)
......
0% ou .
You are about to add 0 people to the discussion. Proceed with caution.
Veuillez vous inscrire ou vous pour commenter