Skip to content

Updated API documentation, PG-4988 #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lachiebol merged 3 commits into from
Feb 24, 2026
Merged

Updated API documentation, PG-4988 #238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a084726
Updated API documentation
lachiebol Feb 24, 2026
c065baa
Fixed codex issues
lachiebol Feb 24, 2026
d69bc54
Added union type examples to description
lachiebol Feb 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 70 additions & 48 deletions API.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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<array{idSite: int, value: mixed}> Alert values grouped by site.
*/
public function getValuesForAlertInPast($idAlert, $subPeriodN)
{
Expand All @@ -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<int>} & array<string, mixed> Alert definition.
* @throws \Exception In case alert does not exist or user has no permission to access alert.
*/
public function getAlert($idAlert)
Expand All @@ -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<array<string, mixed>> Alerts accessible to the current user.
*/
public function getAlerts($idSites, $ifSuperUserReturnAllAlerts = false)
{
Expand All @@ -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<string> $additionalEmails Additional email recipients.
* @param list<string> $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 = '')
{
Expand Down Expand Up @@ -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<string> $additionalEmails Additional email recipients.
* @param list<string> $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 = '')
{
Expand All @@ -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)
{
Expand All @@ -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<array<string, mixed>> Triggered alerts for the current user and requested sites.
*/
public function getTriggeredAlerts($idSites)
{
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
},
Expand Down