From 94b3554180a7d1b52e9b47c428dca5298f1757cf Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Tue, 21 Apr 2026 14:32:15 +1200 Subject: [PATCH 1/2] docs: updated API documentation to be more consistent --- API.php | 86 +++++++++++++++++++++++++++++---------------------------- 1 file changed, 44 insertions(+), 42 deletions(-) diff --git a/API.php b/API.php index af91de8..1d1fb04 100755 --- a/API.php +++ b/API.php @@ -15,7 +15,9 @@ use Piwik\Site; /** - * Provides API methods to create, update, fetch, and delete custom alerts. + * Exposes Custom Alerts API endpoints for managing alert definitions and reading triggered alert data. + * These methods let callers create, update, fetch, delete, and evaluate alerts for one or more sites. + * * @method static \Piwik\Plugins\CustomAlerts\API getInstance() */ class API extends \Piwik\Plugin\API @@ -33,12 +35,12 @@ public function __construct(Processor $processor, Validator $validator) } /** - * Calculates the alert value for each site for the given days/weeks/months in past. If the period of the alert is - * weeks and subPeriodN is "7" it will return the value for the week 7 weeks ago. Set subPeriodN to "0" to test the - * current day/week/month. + * Returns the computed alert value for each site linked to an alert for a past or current period. + * Use 0 to evaluate the current period, 1 for the previous matching period, and so on. * * @param int $idAlert Alert ID to evaluate. - * @param int $subPeriodN Number of periods in the past to evaluate. Use 0 for the current period. + * @param int|string $subPeriodN Number of periods in the past to evaluate. + * Use 0 for the current day, week, or month. * * @return list Alert values grouped by site. */ @@ -58,12 +60,11 @@ public function getValuesForAlertInPast($idAlert, $subPeriodN) } /** - * Returns a single alert. + * Returns a single custom alert definition. * * @param int $idAlert Alert ID to fetch. * - * @return array{id_sites: list} & array Alert definition. - * @throws \Exception In case alert does not exist or user has no permission to access alert. + * @return array{id_sites: list} & array Alert definition including the configured site IDs. */ public function getAlert($idAlert) { @@ -84,13 +85,13 @@ private function getModel() } /** - * Returns the Alerts that are defined on the idSites given. + * Returns the custom alerts configured for the requested sites. * * @param string|array $idSites Website ID(s) to query. * Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"]. - * @param bool $ifSuperUserReturnAllAlerts Whether to return all users' alerts when the current user is super user. + * @param bool $ifSuperUserReturnAllAlerts Whether a super user should receive alerts created by all users. * - * @return list> Alerts accessible to the current user. + * @return list> Alert definitions accessible to the current user for the requested sites. */ public function getAlerts($idSites, $ifSuperUserReturnAllAlerts = false) { @@ -114,34 +115,34 @@ public function getAlerts($idSites, $ifSuperUserReturnAllAlerts = false) } /** - * Creates an Alert for given website(s). + * Creates a custom alert for one or more sites. * * @param string $name Alert name. * @param string|array $idSites Website ID(s) to query. * Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"]. * @param 'day'|'week'|'month' $period Alert period. * Allowed values: day, week, month. - * @param bool $emailMe Whether to send email notifications to the current user. - * @param list $additionalEmails Additional email recipients. - * @param list $phoneNumbers Mobile Messaging recipients. - * @param string $metric Metric unique ID (for example nb_uniq_visits, sum_visit_length). - * @param string $metricCondition Metric comparison condition. + * @param bool $emailMe Whether to notify the current user by email when the alert triggers. + * @param list $additionalEmails Additional email recipients for email notifications. + * @param list $phoneNumbers Mobile Messaging recipients when the mobile channel is enabled. + * @param string $metric Metric unique ID to evaluate, for example nb_uniq_visits or sum_visit_length. + * @param string $metricCondition Comparison rule to apply to the metric. * Allowed values: less_than, greater_than, decrease_more_than, * increase_more_than, percentage_decrease_more_than, * percentage_increase_more_than. - * @param float|int|string $metricValue Metric to check for the selected report. + * @param float|int|string $metricValue Threshold value to compare the selected metric against. * @param int $comparedTo Number of prior periods to compare against. * Allowed values by period: day => 1, 7, 365; week => 1; month => 1, 12. - * @param string $reportUniqueId Report unique ID in format module_action. - * @param false|string $reportCondition Group condition to apply. + * @param string $reportUniqueId Report unique ID in module_action format. + * @param false|string $reportCondition Optional dimension filter condition for report rows. * Allowed values: matches_any, matches_exactly, does_not_match_exactly, * matches_regex, does_not_match_regex, contains, does_not_contain, * starts_with, does_not_start_with, ends_with, does_not_end_with. - * @param false|string $reportValue Value used by $reportCondition. - * @param list<'email'|'mobile'|'slack'|'teams'> $reportMediums Delivery channels. + * @param false|string $reportValue Value to match when $reportCondition is provided. + * @param list<'email'|'mobile'|'slack'|'teams'> $reportMediums Delivery channels to use for notifications. * Allowed values: email, mobile, slack, teams. - * @param string $slackChannelID Slack channel ID when "slack" medium is enabled. - * @param string $msTeamsWebhookUrl Microsoft Teams webhook URL when "teams" medium is enabled. + * @param string $slackChannelID Slack channel ID when the slack channel is enabled. + * @param string $msTeamsWebhookUrl Microsoft Teams webhook URL when the teams channel is enabled. * @return int ID of the newly created alert. */ public function addAlert($name, $idSites, $period, $emailMe, $additionalEmails, $phoneNumbers, $metric, $metricCondition, $metricValue, $comparedTo, $reportUniqueId, $reportCondition = false, $reportValue = false, array $reportMediums = [], string $slackChannelID = '', string $msTeamsWebhookUrl = '') @@ -222,35 +223,35 @@ private function checkAlert($idSites, $name, $period, &$emailMe, &$additionalEma } /** - * Edits an Alert for given website(s). + * Updates an existing custom alert. * * @param int $idAlert Alert ID to update. - * @param string $name Name of alert. + * @param string $name Alert name. * @param string|array $idSites Website ID(s) to query. * Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"]. * @param 'day'|'week'|'month' $period Alert period. * Allowed values: day, week, month. - * @param bool $emailMe Whether to send email notifications to the current user. - * @param list $additionalEmails Additional email recipients. - * @param list $phoneNumbers Mobile Messaging recipients. - * @param string $metric Metric unique ID (for example nb_uniq_visits, sum_visit_length). - * @param string $metricCondition Metric comparison condition. + * @param bool $emailMe Whether to notify the current user by email when the alert triggers. + * @param list $additionalEmails Additional email recipients for email notifications. + * @param list $phoneNumbers Mobile Messaging recipients when the mobile channel is enabled. + * @param string $metric Metric unique ID to evaluate, for example nb_uniq_visits or sum_visit_length. + * @param string $metricCondition Comparison rule to apply to the metric. * Allowed values: less_than, greater_than, decrease_more_than, * increase_more_than, percentage_decrease_more_than, * percentage_increase_more_than. - * @param float|int|string $metricValue Metric to check for the selected report. + * @param float|int|string $metricValue Threshold value to compare the selected metric against. * @param int $comparedTo Number of prior periods to compare against. * Allowed values by period: day => 1, 7, 365; week => 1; month => 1, 12. - * @param string $reportUniqueId Report unique ID in format module_action. - * @param false|string $reportCondition Group condition to apply. + * @param string $reportUniqueId Report unique ID in module_action format. + * @param false|string $reportCondition Optional dimension filter condition for report rows. * Allowed values: matches_any, matches_exactly, does_not_match_exactly, * matches_regex, does_not_match_regex, contains, does_not_contain, * starts_with, does_not_start_with, ends_with, does_not_end_with. - * @param false|string $reportValue Value used by $reportCondition. - * @param list<'email'|'mobile'|'slack'|'teams'> $reportMediums Delivery channels. + * @param false|string $reportValue Value to match when $reportCondition is provided. + * @param list<'email'|'mobile'|'slack'|'teams'> $reportMediums Delivery channels to use for notifications. * Allowed values: email, mobile, slack, teams. - * @param string $slackChannelID Slack channel ID when "slack" medium is enabled. - * @param string $msTeamsWebhookUrl Microsoft Teams webhook URL when "teams" medium is enabled. + * @param string $slackChannelID Slack channel ID when the slack channel is enabled. + * @param string $msTeamsWebhookUrl Microsoft Teams webhook URL when the teams channel is enabled. * * @return int Updated alert ID. */ @@ -276,10 +277,11 @@ public function editAlert($idAlert, $name, $idSites, $period, $emailMe, $additio } /** - * Delete alert by id. + * Deletes an existing custom alert. * * @param int $idAlert Alert ID to delete. - * @throws \Exception In case alert does not exist or user has no permission to access alert. + * + * @return void */ public function deleteAlert($idAlert) { @@ -290,12 +292,12 @@ public function deleteAlert($idAlert) } /** - * Get triggered alerts. + * Returns triggered alerts for the current user and requested sites. * * @param string|array $idSites Website ID(s) to query. * Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"]. * - * @return list> Triggered alerts for the current user and requested sites. + * @return list> Triggered alert entries for the current user and requested sites. */ public function getTriggeredAlerts($idSites) { From d20e9f605985a891582b744f1b29ef92627eda48 Mon Sep 17 00:00:00 2001 From: Lachlan Reynolds Date: Wed, 22 Apr 2026 11:26:50 +1200 Subject: [PATCH 2/2] Updated changelog --- CHANGELOG.md | 1 + plugin.json | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a29f273..a2ada0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ ## Changelog +* 5.2.6 - 2026-04-27 - Updated API documentation * 5.2.5 - 2026-03-30 - Added escaping for report_matched value * 5.2.4 - 2026-03-02 - Updated API documentation * 5.2.3 - 2026-02-05 - Alerts now get deleted when a user's site access is revoked diff --git a/plugin.json b/plugin.json index bcc9ad8..ce45810 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "name": "CustomAlerts", "description": "Create custom Alerts to be notified of important changes on your website or app! ", - "version": "5.2.5", + "version": "5.2.6", "require": { "matomo": ">=5.0.0-b1,<6.0.0-b1" },