diff --git a/API.php b/API.php index 6244793..af91de8 100755 --- a/API.php +++ b/API.php @@ -15,7 +15,7 @@ use Piwik\Site; /** - * + * Provides API methods to create, update, fetch, and delete custom alerts. * @method static \Piwik\Plugins\CustomAlerts\API getInstance() */ class API extends \Piwik\Plugin\API @@ -37,10 +37,10 @@ public function __construct(Processor $processor, Validator $validator) * 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. * - * @param int $idAlert - * @param int $subPeriodN + * @param int $idAlert Alert ID to evaluate. + * @param int $subPeriodN Number of periods in the past to evaluate. Use 0 for the current period. * - * @return array + * @return list Alert values grouped by site. */ public function getValuesForAlertInPast($idAlert, $subPeriodN) { @@ -60,9 +60,9 @@ public function getValuesForAlertInPast($idAlert, $subPeriodN) /** * Returns a single alert. * - * @param int $idAlert + * @param int $idAlert Alert ID to fetch. * - * @return array + * @return array{id_sites: list} & array Alert definition. * @throws \Exception In case alert does not exist or user has no permission to access alert. */ public function getAlert($idAlert) @@ -86,10 +86,11 @@ private function getModel() /** * Returns the Alerts that are defined on the idSites given. * - * @param array $idSites - * @param bool $ifSuperUserReturnAllAlerts + * @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. * - * @return array + * @return list> Alerts accessible to the current user. */ public function getAlerts($idSites, $ifSuperUserReturnAllAlerts = false) { @@ -115,23 +116,33 @@ public function getAlerts($idSites, $ifSuperUserReturnAllAlerts = false) /** * Creates an Alert for given website(s). * - * @param string $name - * @param mixed $idSites - * @param string $period - * @param bool $emailMe - * @param array $additionalEmails - * @param array $phoneNumbers - * @param string $metric (nb_uniq_visits, sum_visit_length, ..) - * @param string $metricCondition - * @param float $metricValue - * @param string $reportUniqueId - * @param int $comparedTo - * @param bool|string $reportCondition - * @param bool|string $reportValue - * @param array $reportMediums - * @param string $slackChannelID - * @param string $msTeamsWebhookUrl - * @return int ID of new 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. + * 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 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. + * 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. + * 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. + * @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 = '') { @@ -213,25 +224,35 @@ private function checkAlert($idSites, $name, $period, &$emailMe, &$additionalEma /** * Edits an Alert for given website(s). * - * @param $idAlert - * @param string $name Name of Alert - * @param mixed $idSites Single int or array of ints of idSites. - * @param string $period Period the alert is defined on. - * @param bool $emailMe - * @param array $additionalEmails - * @param array $phoneNumbers - * @param string $metric (nb_uniq_visits, sum_visit_length, ..) - * @param string $metricCondition - * @param float $metricValue - * @param string $reportUniqueId - * @param int $comparedTo - * @param bool|string $reportCondition - * @param bool|string $reportValue - * @param array $reportMediums - * @param string $slackChannelID - * @param string $msTeamsWebhookUrl + * @param int $idAlert Alert ID to update. + * @param string $name Name of alert. + * @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. + * 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 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. + * 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. + * 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. * - * @return boolean + * @return int Updated alert ID. */ public function editAlert($idAlert, $name, $idSites, $period, $emailMe, $additionalEmails, $phoneNumbers, $metric, $metricCondition, $metricValue, $comparedTo, $reportUniqueId, $reportCondition = false, $reportValue = false, array $reportMediums = [], string $slackChannelID = '', string $msTeamsWebhookUrl = '') { @@ -257,8 +278,8 @@ public function editAlert($idAlert, $name, $idSites, $period, $emailMe, $additio /** * Delete alert by id. * - * @param int $idAlert - * @throws \Exception + * @param int $idAlert Alert ID to delete. + * @throws \Exception In case alert does not exist or user has no permission to access alert. */ public function deleteAlert($idAlert) { @@ -271,9 +292,10 @@ public function deleteAlert($idAlert) /** * Get triggered alerts. * - * @param int[] $idSites + * @param string|array $idSites Website ID(s) to query. + * Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"]. * - * @return array + * @return list> Triggered alerts for the current user and requested sites. */ public function getTriggeredAlerts($idSites) { diff --git a/CHANGELOG.md b/CHANGELOG.md index 7317bb3..3de326d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ ## Changelog +* 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 * 5.2.2 - 2026-01-19 - Added tooltips in add/edit alerts, manage alerts & in the inline text for the delivery method * 5.2.1 - 2025-12-08 - Fixes default value showing up as empty entry for alert_mediums diff --git a/plugin.json b/plugin.json index b864765..5650592 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.3", + "version": "5.2.4", "require": { "matomo": ">=5.0.0-b1,<6.0.0-b1" },