API Reference

Request

Piwik\API\

Request

Dispatches API requests to the appropriate API method.

The Request class is used throughout Matomo (formerly 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: applying generic filters, applying queued filters, and handling 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 correct approach.

Post-processing

The return value of API methods undergo some extra processing before being returned by Request.

Output Formats

The value returned by Request will be serialized to a certain format before being returned.

Examples

Basic Usage

$request = new Request('method=UserLanguage.getLanguage&idSite=1&date=yesterday&period=week'
                     . '&format=xml&filter_limit=5&filter_offset=0')
$result = $request->process();
echo $result;

Getting a unrendered DataTable

// use the convenience method 'processRequest'
$dataTable = Request::processRequest('UserLanguage.getLanguage', array(
    'idSite' => 1,
    'date' => 'yesterday',
    'period' => 'week',
    'filter_limit' => 5,
    'filter_offset' => 0

    'format' => 'original', // this is the important bit
));
echo "This DataTable has " . $dataTable->getRowsCount() . " rows.";

Methods

The class defines the following methods:

getRequestArrayFromString()

Converts the supplied request string into an array of query parameter name/value mappings. The current query parameters (everything in $_GET and $_POST) are forwarded to request array before it is returned.

Signature

  • It accepts the following parameter(s):
    • $request (string|array|null) — The base request string or array, eg, 'module=UserLanguage&action=getLanguage'.
    • $defaultRequest (array) — Default query parameters. If a query parameter is absent in $request, it will be loaded from this. Defaults to $_GET + $_POST.
  • It returns a array value.

__construct()

Constructor.

Signature

  • It accepts the following parameter(s):
    • $request (string|array) — Query string that defines the API call (must at least contain a method parameter), eg, 'method=UserLanguage.getLanguage&idSite=1&date=yesterday&period=week&format=xml' If a request is not provided, then we use the values in the $_GET and $_POST superglobals.
    • $defaultRequest (array) — Default query parameters. If a query parameter is absent in $request, it will be loaded from this. Defaults to $_GET + $_POST.

process()

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
  • removing columns based on the values of the hideColumns and showColumns query parameters
  • filtering rows if the label query parameter is set
  • converting the result to the appropriate format (ie, XML, JSON, etc.)

If 'original' is supplied for the output format, the result is returned as a PHP object.

Signature

  • Returns: DataTable|Piwik\API\Map|string — The data resulting from the API call.
  • It throws one of the following exceptions:
    • Piwik\Exception\PluginDeactivatedException — if the module plugin is not activated.
    • 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.

getClassNameAPI()

Returns the name of a plugin's API class by plugin name.

Signature

  • It accepts the following parameter(s):

    • $plugin (string) — The plugin name, eg, 'Referrers'.

  • Returns: string — The fully qualified API class name, eg, '\Piwik\Plugins\Referrers\API'.

isRootRequestApiRequest()

Detect if the root request (the actual request) is an API request or not. To detect whether an API is currently request within any request, have a look at isApiRequest().

Signature

  • It returns a bool value.
  • It throws one of the following exceptions:

isCurrentApiRequestTheRootApiRequest()

Checks if the currently executing API request is the root API request or not.

Note: the "root" API request is the first request made. Within that request, further API methods can be called programmatically. These requests are considered "child" API requests.

Signature

  • It returns a bool value.
  • It throws one of the following exceptions:

isApiRequest()

Detect if request is an API request. Meaning the module is 'API' and an API method having a valid format was specified. Note that this method will return true even if the actual request is for example a regular UI reporting page request but within this request we are currently processing an API request (eg a controller calls Request::processRequest('API.getMatomoVersion')). To find out if the root request is an API request or not, call isRootRequestApiRequest()

Signature

  • It accepts the following parameter(s):
    • $request (array) — eg array('module' => 'API', 'method' => 'Test.getMethod')
  • It returns a bool value.
  • It throws one of the following exceptions:

getMethodIfApiRequest()

Returns the current API method being executed, if the current request is an API request.

Signature

  • It accepts the following parameter(s):

    • $request (array) — eg array('module' => 'API', 'method' => 'Test.getMethod')

  • Returns: string|null —

  • It throws one of the following exceptions:

isTokenAuthProvidedSecurely()

Returns true if a token_auth parameter was supplied via a secure mechanism and is not present as a URL parameter At the moment POST requests are checked, but in future other mechanism such as Authorisation HTTP header and bearer tokens might be used as well.

Signature

  • Returns: bool — True if token was supplied in a secure way

processRequest()

Helper method that processes an API request in one line using the variables in $_GET and $_POST.

Signature

  • It accepts the following parameter(s):

    • $method (string) — The API method to call, ie, 'Actions.getPageTitles'.
    • $paramOverride (array) — The parameter name-value pairs to use instead of what's in $_GET & $_POST.
    • $defaultRequest (array) — Default query parameters. If a query parameter is absent in $request, it will be loaded from this. Defaults to $_GET + $_POST. To avoid using any parameters from $_GET or $_POST, set this to an empty array().

  • Returns: mixed — The result of the API request. See process().

getRequestParametersGET()

Returns the original request parameters in the current query string as an array mapping query parameter names with values. The result of this function will not be affected by any modifications to $_GET and will not include parameters in $_POST.

Signature

  • It returns a array value.

getBaseReportUrl()

Returns the URL for the current requested report w/o any filter parameters.

Signature

  • It accepts the following parameter(s):
    • $module (string) — The API module.
    • $action (string) — The API action.
    • $queryParams (array) — Query parameter overrides.
  • It returns a string value.

getCurrentUrlWithoutGenericFilters()

Returns the current URL without generic filter query parameters.

Signature

  • It accepts the following parameter(s):
    • $params (array) — Query parameter values to override in the new URL.
  • It returns a string value.

shouldLoadFlatten()

Signature

  • It returns a bool value.

getRawSegmentFromRequest()

Returns the segment query parameter from the original request, without modifications.

Signature

  • Returns: array|bool —