From 74492652520bdd2e1438a01eab81f5b47cd65bb7 Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Tue, 24 Feb 2026 16:47:49 +1300 Subject: [PATCH] Updated api documentation --- API.php | 59 ++++++++++++++++++++++++++++++++++------------------ CHANGELOG.md | 3 +++ plugin.json | 2 +- 3 files changed, 43 insertions(+), 21 deletions(-) diff --git a/API.php b/API.php index 91f5127..a8c030b 100644 --- a/API.php +++ b/API.php @@ -19,7 +19,9 @@ use Piwik\Piwik; /** - * The Custom Variables API lets you access reports for your Custom Variables names and values. + * The Custom Variables API lets you access reports for your + * Custom Variables + * names and values. * * @method static \Piwik\Plugins\CustomVariables\API getInstance() */ @@ -49,15 +51,22 @@ protected function getDataTable($idSite, $period, $date, $segment, $expanded, $f } /** - * @param int $idSite - * @param string $period - * @param Date $date - * @param string|bool $segment - * @param bool $expanded - * @param bool $_leavePiwikCoreVariables - * @param bool $flat + * Returns custom variable names for a site. * - * @return DataTable|DataTable\Map + * @param int $idSite The numeric ID of the website to query. + * @param string $period The period to process, processes data for the period containing the specified date. + * Allowed values: "day", "week", "month", "year", "range". + * @param string|Date $date The date or date range to process. + * 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), + * or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX). + * @param string|false $segment (Optional) Custom segment to filter the report. + * Example: "referrerName==twitter.com" + * Supports AND (;) and OR (,) operators. + * [See documentation:](https://developer.matomo.org/api-reference/reporting-api-segmentation) + * @param bool $expanded Whether to return subtables as nested data. + * @param bool $_leavePiwikCoreVariables Whether to keep Matomo reserved custom variable rows. + * @param bool $flat Whether to flatten subtables into a single table. + * @return DataTable|DataTable\Map Custom variable names report. */ public function getCustomVariables($idSite, $period, $date, $segment = false, $expanded = false, $_leavePiwikCoreVariables = false, $flat = false) { @@ -99,14 +108,21 @@ public static function getReservedCustomVariableKeys() } /** - * @param int $idSite - * @param string $period - * @param Date $date - * @param int $idSubtable - * @param string|bool $segment - * @param bool $_leavePriceViewedColumn + * Returns custom variable values for a specific custom variable name row. * - * @return DataTable|DataTable\Map + * @param int $idSite The numeric ID of the website to query. + * @param string $period The period to process, processes data for the period containing the specified date. + * Allowed values: "day", "week", "month", "year", "range". + * @param string|Date $date The date or date range to process. + * 'YYYY-MM-DD', magic keywords (today, yesterday, lastWeek, lastMonth, lastYear), + * or date range (ie, 'YYYY-MM-DD,YYYY-MM-DD', lastX, previousX). + * @param int|string|false $idSubtable Subtable ID to load, 'all' to load all subtables, or false for root. + * @param string|false $segment (Optional) Custom segment to filter the report. + * Example: "referrerName==twitter.com" + * Supports AND (;) and OR (,) operators. + * [See documentation:](https://developer.matomo.org/api-reference/reporting-api-segmentation) + * @param bool $_leavePriceViewedColumn Whether to keep the `price_viewed` column instead of renaming it to `price`. + * @return DataTable|DataTable\Map Custom variable values report. */ public function getCustomVariablesValuesFromNameId($idSite, $period, $date, $idSubtable, $segment = false, $_leavePriceViewedColumn = false) { @@ -127,11 +143,14 @@ public function getCustomVariablesValuesFromNameId($idSite, $period, $date, $idS } /** - * Get a list of all available custom variable slots (scope + index) and which names have been used so far in - * each slot since the beginning of the website. + * Returns all custom variable slots and the names used in each slot since the beginning of the website. * - * @param int $idSite - * @return array + * @param int $idSite The numeric ID of the website to query. + * @return array + * }> List of custom variable slot usages grouped by scope and index. */ public function getUsagesOfSlots($idSite) { diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ed5b32..3454d56 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ # CHANGELOG +5.0.5 - 2026-02-03 +- Updated API documentation + 5.0.4 - 2025-01-20 - Added missing license file diff --git a/plugin.json b/plugin.json index c5fc70f..8f5e59a 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "name": "CustomVariables", "description": "Categorise your visitors and actions with custom name-value pairs. Segment by these values and get more insights to draw the right conclusions.", - "version": "5.0.4", + "version": "5.0.5", "keywords": ["custom variables"], "license": "GPL v3+", "homepage": "https://matomo.org",