Skip to content

Commit 77d8e3c

Browse files
lachiebollachiebol
authored
Updated API documentation, PG-4988 (#238)
* Updated API documentation * Fixed codex issues * Added union type examples to description
1 parent 919f2bb commit 77d8e3c

3 files changed

Lines changed: 72 additions & 49 deletions

File tree

‎API.php‎

Lines changed: 70 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
use Piwik\Site;
1616

1717
/**
18-
*
18+
* Provides API methods to create, update, fetch, and delete custom alerts.
1919
* @method static \Piwik\Plugins\CustomAlerts\API getInstance()
2020
*/
2121
class API extends \Piwik\Plugin\API
@@ -37,10 +37,10 @@ public function __construct(Processor $processor, Validator $validator)
3737
* weeks and subPeriodN is "7" it will return the value for the week 7 weeks ago. Set subPeriodN to "0" to test the
3838
* current day/week/month.
3939
*
40-
* @param int $idAlert
41-
* @param int $subPeriodN
40+
* @param int $idAlert Alert ID to evaluate.
41+
* @param int $subPeriodN Number of periods in the past to evaluate. Use 0 for the current period.
4242
*
43-
* @return array
43+
* @return list<array{idSite: int, value: mixed}> Alert values grouped by site.
4444
*/
4545
public function getValuesForAlertInPast($idAlert, $subPeriodN)
4646
{
@@ -60,9 +60,9 @@ public function getValuesForAlertInPast($idAlert, $subPeriodN)
6060
/**
6161
* Returns a single alert.
6262
*
63-
* @param int $idAlert
63+
* @param int $idAlert Alert ID to fetch.
6464
*
65-
* @return array
65+
* @return array{id_sites: list<int>} & array<string, mixed> Alert definition.
6666
* @throws \Exception In case alert does not exist or user has no permission to access alert.
6767
*/
6868
public function getAlert($idAlert)
@@ -86,10 +86,11 @@ private function getModel()
8686
/**
8787
* Returns the Alerts that are defined on the idSites given.
8888
*
89-
* @param array $idSites
90-
* @param bool $ifSuperUserReturnAllAlerts
89+
* @param string|array $idSites Website ID(s) to query.
90+
* Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"].
91+
* @param bool $ifSuperUserReturnAllAlerts Whether to return all users' alerts when the current user is super user.
9192
*
92-
* @return array
93+
* @return list<array<string, mixed>> Alerts accessible to the current user.
9394
*/
9495
public function getAlerts($idSites, $ifSuperUserReturnAllAlerts = false)
9596
{
@@ -115,23 +116,33 @@ public function getAlerts($idSites, $ifSuperUserReturnAllAlerts = false)
115116
/**
116117
* Creates an Alert for given website(s).
117118
*
118-
* @param string $name
119-
* @param mixed $idSites
120-
* @param string $period
121-
* @param bool $emailMe
122-
* @param array $additionalEmails
123-
* @param array $phoneNumbers
124-
* @param string $metric (nb_uniq_visits, sum_visit_length, ..)
125-
* @param string $metricCondition
126-
* @param float $metricValue
127-
* @param string $reportUniqueId
128-
* @param int $comparedTo
129-
* @param bool|string $reportCondition
130-
* @param bool|string $reportValue
131-
* @param array $reportMediums
132-
* @param string $slackChannelID
133-
* @param string $msTeamsWebhookUrl
134-
* @return int ID of new Alert
119+
* @param string $name Alert name.
120+
* @param string|array $idSites Website ID(s) to query.
121+
* Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"].
122+
* @param 'day'|'week'|'month' $period Alert period.
123+
* Allowed values: day, week, month.
124+
* @param bool $emailMe Whether to send email notifications to the current user.
125+
* @param list<string> $additionalEmails Additional email recipients.
126+
* @param list<string> $phoneNumbers Mobile Messaging recipients.
127+
* @param string $metric Metric unique ID (for example nb_uniq_visits, sum_visit_length).
128+
* @param string $metricCondition Metric comparison condition.
129+
* Allowed values: less_than, greater_than, decrease_more_than,
130+
* increase_more_than, percentage_decrease_more_than,
131+
* percentage_increase_more_than.
132+
* @param float|int|string $metricValue Metric to check for the selected report.
133+
* @param int $comparedTo Number of prior periods to compare against.
134+
* Allowed values by period: day => 1, 7, 365; week => 1; month => 1, 12.
135+
* @param string $reportUniqueId Report unique ID in format module_action.
136+
* @param false|string $reportCondition Group condition to apply.
137+
* Allowed values: matches_any, matches_exactly, does_not_match_exactly,
138+
* matches_regex, does_not_match_regex, contains, does_not_contain,
139+
* starts_with, does_not_start_with, ends_with, does_not_end_with.
140+
* @param false|string $reportValue Value used by $reportCondition.
141+
* @param list<'email'|'mobile'|'slack'|'teams'> $reportMediums Delivery channels.
142+
* Allowed values: email, mobile, slack, teams.
143+
* @param string $slackChannelID Slack channel ID when "slack" medium is enabled.
144+
* @param string $msTeamsWebhookUrl Microsoft Teams webhook URL when "teams" medium is enabled.
145+
* @return int ID of the newly created alert.
135146
*/
136147
public function addAlert($name, $idSites, $period, $emailMe, $additionalEmails, $phoneNumbers, $metric, $metricCondition, $metricValue, $comparedTo, $reportUniqueId, $reportCondition = false, $reportValue = false, array $reportMediums = [], string $slackChannelID = '', string $msTeamsWebhookUrl = '')
137148
{
@@ -213,25 +224,35 @@ private function checkAlert($idSites, $name, $period, &$emailMe, &$additionalEma
213224
/**
214225
* Edits an Alert for given website(s).
215226
*
216-
* @param $idAlert
217-
* @param string $name Name of Alert
218-
* @param mixed $idSites Single int or array of ints of idSites.
219-
* @param string $period Period the alert is defined on.
220-
* @param bool $emailMe
221-
* @param array $additionalEmails
222-
* @param array $phoneNumbers
223-
* @param string $metric (nb_uniq_visits, sum_visit_length, ..)
224-
* @param string $metricCondition
225-
* @param float $metricValue
226-
* @param string $reportUniqueId
227-
* @param int $comparedTo
228-
* @param bool|string $reportCondition
229-
* @param bool|string $reportValue
230-
* @param array $reportMediums
231-
* @param string $slackChannelID
232-
* @param string $msTeamsWebhookUrl
227+
* @param int $idAlert Alert ID to update.
228+
* @param string $name Name of alert.
229+
* @param string|array $idSites Website ID(s) to query.
230+
* Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"].
231+
* @param 'day'|'week'|'month' $period Alert period.
232+
* Allowed values: day, week, month.
233+
* @param bool $emailMe Whether to send email notifications to the current user.
234+
* @param list<string> $additionalEmails Additional email recipients.
235+
* @param list<string> $phoneNumbers Mobile Messaging recipients.
236+
* @param string $metric Metric unique ID (for example nb_uniq_visits, sum_visit_length).
237+
* @param string $metricCondition Metric comparison condition.
238+
* Allowed values: less_than, greater_than, decrease_more_than,
239+
* increase_more_than, percentage_decrease_more_than,
240+
* percentage_increase_more_than.
241+
* @param float|int|string $metricValue Metric to check for the selected report.
242+
* @param int $comparedTo Number of prior periods to compare against.
243+
* Allowed values by period: day => 1, 7, 365; week => 1; month => 1, 12.
244+
* @param string $reportUniqueId Report unique ID in format module_action.
245+
* @param false|string $reportCondition Group condition to apply.
246+
* Allowed values: matches_any, matches_exactly, does_not_match_exactly,
247+
* matches_regex, does_not_match_regex, contains, does_not_contain,
248+
* starts_with, does_not_start_with, ends_with, does_not_end_with.
249+
* @param false|string $reportValue Value used by $reportCondition.
250+
* @param list<'email'|'mobile'|'slack'|'teams'> $reportMediums Delivery channels.
251+
* Allowed values: email, mobile, slack, teams.
252+
* @param string $slackChannelID Slack channel ID when "slack" medium is enabled.
253+
* @param string $msTeamsWebhookUrl Microsoft Teams webhook URL when "teams" medium is enabled.
233254
*
234-
* @return boolean
255+
* @return int Updated alert ID.
235256
*/
236257
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 = '')
237258
{
@@ -257,8 +278,8 @@ public function editAlert($idAlert, $name, $idSites, $period, $emailMe, $additio
257278
/**
258279
* Delete alert by id.
259280
*
260-
* @param int $idAlert
261-
* @throws \Exception
281+
* @param int $idAlert Alert ID to delete.
282+
* @throws \Exception In case alert does not exist or user has no permission to access alert.
262283
*/
263284
public function deleteAlert($idAlert)
264285
{
@@ -271,9 +292,10 @@ public function deleteAlert($idAlert)
271292
/**
272293
* Get triggered alerts.
273294
*
274-
* @param int[] $idSites
295+
* @param string|array $idSites Website ID(s) to query.
296+
* Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"].
275297
*
276-
* @return array
298+
* @return list<array<string, mixed>> Triggered alerts for the current user and requested sites.
277299
*/
278300
public function getTriggeredAlerts($idSites)
279301
{

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
## Changelog
22

3+
* 5.2.4 - 2026-03-02 - Updated API documentation
34
* 5.2.3 - 2026-02-05 - Alerts now get deleted when a user's site access is revoked
45
* 5.2.2 - 2026-01-19 - Added tooltips in add/edit alerts, manage alerts & in the inline text for the delivery method
56
* 5.2.1 - 2025-12-08 - Fixes default value showing up as empty entry for alert_mediums

‎plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "CustomAlerts",
33
"description": "Create custom Alerts to be notified of important changes on your website or app! ",
4-
"version": "5.2.3",
4+
"version": "5.2.4",
55
"require": {
66
"matomo": ">=5.0.0-b1,<6.0.0-b1"
77
},

0 commit comments

Comments
 (0)