From 03c9289d0fb9ad084ffba47b756b541d0385e2d9 Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Tue, 21 Apr 2026 14:36:57 +1200 Subject: [PATCH 1/2] docs: updated API documentation to be more consistent --- API.php | 43 ++++++++++++++++++++----------------------- 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/API.php b/API.php index 525814e..c8066a4 100644 --- a/API.php +++ b/API.php @@ -19,9 +19,7 @@ use Piwik\Piwik; /** - * The Custom Variables API lets you access reports for your - * Custom Variables - * names and values. + * Exposes reporting API endpoints for Custom Variables names, values, and slot usage. * * @method static \Piwik\Plugins\CustomVariables\API getInstance() */ @@ -57,19 +55,18 @@ protected function getDataTable($idSite, $period, $date, $segment, $expanded, $f * - Single site ID (e.g. 1) * - Multiple site IDs (e.g. [1, 4, 5]) * - Comma-separated list ("1,4,5") or "all" - * @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 'day'|'week'|'month'|'year'|'range' $period The period to process, processes data for the period + * containing the specified date. + * @param string $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|null $segment Custom segment to filter the report. + * Example: "referrerName==example.com" + * Supports AND (;) and OR (,) operators. * @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. + * @return DataTable|DataTable\Map Custom variable names report for the requested site selection and period. */ public function getCustomVariables($idSite, $period, $date, $segment = false, $expanded = false, $_leavePiwikCoreVariables = false, $flat = false) { @@ -117,18 +114,17 @@ public static function getReservedCustomVariableKeys() * - Single site ID (e.g. 1) * - Multiple site IDs (e.g. [1, 4, 5]) * - Comma-separated list ("1,4,5") or "all" - * @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 'day'|'week'|'month'|'year'|'range' $period The period to process, processes data for the period + * containing the specified date. + * @param string $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 string|false|null $segment Custom segment to filter the report. + * Example: "referrerName==example.com" + * Supports AND (;) and OR (,) operators. * @param bool $_leavePriceViewedColumn Whether to keep the `price_viewed` column instead of renaming it to `price`. - * @return DataTable|DataTable\Map Custom variable values report. + * @return DataTable|DataTable\Map Custom variable values report for the requested custom variable name row. */ public function getCustomVariablesValuesFromNameId($idSite, $period, $date, $idSubtable, $segment = false, $_leavePriceViewedColumn = false) { @@ -152,6 +148,7 @@ public function getCustomVariablesValuesFromNameId($idSite, $period, $date, $idS * Returns all custom variable slots and the names used in each slot since the beginning of the website. * * @param int $idSite The numeric ID of the website to query. + * * @return array Date: Wed, 22 Apr 2026 11:30:12 +1200 Subject: [PATCH 2/2] Updated changelog --- CHANGELOG.md | 3 +++ plugin.json | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b9024dc..75252cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ # CHANGELOG +5.0.6 - 2026-04-27 +- Updated API documentation + 5.0.5 - 2026-03-02 - Updated API documentation diff --git a/plugin.json b/plugin.json index 8f5e59a..4d16ad6 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.5", + "version": "5.0.6", "keywords": ["custom variables"], "license": "GPL v3+", "homepage": "https://matomo.org",