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

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&parameter_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)