Skip to content

Updated API documentation for Goals plugin, #PG-4941 #24248

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

Open
lachiebol wants to merge 3 commits into
base: 5.x-dev
Choose a base branch
from
+150 −38
Open

Updated API documentation for Goals plugin, #PG-4941 #24248

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bb003b9
Updated API documentation for Goals plugin
lachiebol Mar 19, 2026
4b074e7
Keep existing class level docs
lachiebol Mar 19, 2026
c8ae9b0
Fixed idSite inconsistency
lachiebol Mar 19, 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
188 changes: 150 additions & 38 deletions plugins/Goals/API.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
<?php

/**
Expand Down Expand Up @@ -61,6 +61,9 @@
/**
* Return a single goal.
*
* @param int $idSite The numeric ID of the website to query.
* @param int $idGoal The numeric ID of the goal to query.
*
* @return ?array An array of goal attributes.
*/
public function getGoal(int $idSite, int $idGoal): ?array
Expand All @@ -79,7 +82,9 @@
/**
* Returns all Goals for a given website, or list of websites
*
* @param string|array $idSite Array or Comma separated list of website IDs to request the goals for
* @param string|array $idSite Website ID(s) to query.
* Accepts comma-separated IDs, "all", numeric IDs as strings, or ["all"].
* @param bool $orderByName If true, sorts the returned goals by name.
*
* @return array Array of Goal attributes,
* indexed by "idgoal" when requesting a single site,
Expand Down Expand Up @@ -155,16 +160,18 @@
/**
* Creates a Goal for a given website.
*
* @param string $name
* @param string $matchAttribute 'url', 'title', 'file', 'external_website', 'manually', 'visit_duration', 'visit_total_actions', 'visit_total_pageviews',
* 'event_action', 'event_category' or 'event_name'
* @param string $pattern eg. purchase-confirmation.htm or numeric value if used with a numeric match attribute
* @param string $patternType 'regex', 'contains', 'exact', or 'greater_than' for numeric match attributes
* @param bool $caseSensitive
* @param bool|float $revenue If set, default revenue to assign to conversions
* @param int $idSite The numeric ID of the website to query.
* @param string $name The goal name.
* @param 'url'|'title'|'file'|'external_website'|'manually'|'visit_duration'|'visit_total_actions'|'visit_total_pageviews'|'event_action'|'event_category'|'event_name' $matchAttribute The attribute to match against.
Copy link
Contributor Author

@lachiebol lachiebol Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit of an eyesore but it technically correct, thoughts?

* @param string $pattern The match pattern, for example a URL fragment or a numeric threshold
* for numeric match attributes.
* @param 'regex'|'contains'|'exact'|'greater_than' $patternType The match type.
* @param bool $caseSensitive If true, uses case-sensitive matching where applicable.
* @param bool|float $revenue If set, default revenue to assign to conversions.
* @param bool $allowMultipleConversionsPerVisit By default, multiple conversions in the same visit will only record the first conversion.
* If set to true, multiple conversions will all be recorded within a visit (useful for Ecommerce goals)
* @param string $description
* @param string $description The goal description.
* @param bool $useEventValueAsRevenue If true, uses the tracked event value as the goal revenue.
*
* @return int ID of the new goal
*/
Expand Down Expand Up @@ -222,15 +229,19 @@
* Updates a Goal description.
* Will not update or re-process the conversions already recorded
*
* @param int $idGoal
* @param $name
* @param $matchAttribute
* @param string $pattern
* @param string $patternType
* @param bool $caseSensitive
* @param bool|float $revenue
* @param bool $allowMultipleConversionsPerVisit
* @param string $description
* @param int $idSite The numeric ID of the website to query.
* @param int $idGoal The numeric ID of the goal to update.
* @param string $name The goal name.
* @param 'url'|'title'|'file'|'external_website'|'manually'|'visit_duration'|'visit_total_actions'|'visit_total_pageviews'|'event_action'|'event_category'|'event_name' $matchAttribute The attribute to match against.
* @param string $pattern The match pattern, for example a URL fragment or a numeric threshold
* for numeric match attributes.
* @param 'regex'|'contains'|'exact'|'greater_than' $patternType The match type.
* @param bool $caseSensitive If true, uses case-sensitive matching where applicable.
* @param bool|float $revenue If set, default revenue to assign to conversions.
* @param bool $allowMultipleConversionsPerVisit If true, allows multiple conversions for
* this goal within a single visit.
* @param string $description The goal description.
* @param bool $useEventValueAsRevenue If true, uses the tracked event value as the goal revenue.
*
* @return void
* @see addGoal() for parameters description
Expand Down Expand Up @@ -351,7 +362,8 @@
* Soft deletes a given Goal.
* Stats data in the archives will still be recorded, but not displayed.
*
* @param int $idGoal
* @param int $idSite The numeric ID of the website to query.
* @param int $idGoal The numeric ID of the goal to delete.
*
* @return void
*/
Expand Down Expand Up @@ -467,20 +479,77 @@
$dataTable->addDataTable($ecommerceViews);
}

/**
* Returns ecommerce item metrics grouped by product SKU.
*
* @param int|string|int[] $idSite Website ID(s) to query.
* - Single site ID (e.g. 1)
* - Multiple site IDs (e.g. [1, 4, 5])
* - Comma-separated list ("1,4,5") or "all"
* @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 bool $abandonedCarts If true, returns items left in abandoned carts instead of purchased items.
* @param string|false $segment Custom segment to filter the report.
* Example: "referrerName==example.com"
* Supports AND (;) and OR (,) operators.
*
* @return DataTable|DataTable\Map
*/
public function getItemsSku($idSite, $period, $date, $abandonedCarts = false, $segment = false)
{
$dataTable = $this->getItems('Goals_ItemsSku', $idSite, $period, $date, $abandonedCarts, $segment);
$dataTable->filter('AddSegmentByLabel', ['productSku']);
return $dataTable;
}

/**
* Returns ecommerce item metrics grouped by product name.
*
* @param int|string|int[] $idSite Website ID(s) to query.
* - Single site ID (e.g. 1)
* - Multiple site IDs (e.g. [1, 4, 5])
* - Comma-separated list ("1,4,5") or "all"
* @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 bool $abandonedCarts If true, returns items left in abandoned carts instead of purchased items.
* @param string|false $segment Custom segment to filter the report.
* Example: "referrerName==example.com"
* Supports AND (;) and OR (,) operators.
*
* @return DataTable|DataTable\Map
*/
public function getItemsName($idSite, $period, $date, $abandonedCarts = false, $segment = false)
{
$dataTable = $this->getItems('Goals_ItemsName', $idSite, $period, $date, $abandonedCarts, $segment);
$dataTable->filter('AddSegmentByLabel', ['productName']);
return $dataTable;
}

/**
* Returns ecommerce item metrics grouped by product category.
*
* @param int|string|int[] $idSite Website ID(s) to query.
* - Single site ID (e.g. 1)
* - Multiple site IDs (e.g. [1, 4, 5])
* - Comma-separated list ("1,4,5") or "all"
* @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 bool $abandonedCarts If true, returns items left in abandoned carts instead of purchased items.
* @param string|false $segment Custom segment to filter the report.
* Example: "referrerName==example.com"
* Supports AND (;) and OR (,) operators.
*
* @return DataTable|DataTable\Map
*/
public function getItemsCategory($idSite, $period, $date, $abandonedCarts = false, $segment = false)
{
$dataTable = $this->getItems('Goals_ItemsCategory', $idSite, $period, $date, $abandonedCarts, $segment);
Expand Down Expand Up @@ -514,15 +583,24 @@
/**
* Returns Goals data.
*
* @param int $idSite
* @param string $period
* @param string $date
* @param bool $segment
* @param bool|int $idGoal
* @param array $columns Array of metrics to fetch: nb_conversions, conversion_rate, revenue
* @param int|string|int[] $idSite Website ID(s) to query.
* - Single site ID (e.g. 1)
* - Multiple site IDs (e.g. [1, 4, 5])
* - Comma-separated list ("1,4,5") or "all"
* @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 $segment Custom segment to filter the report.
* Example: "referrerName==example.com"
* Supports AND (;) and OR (,) operators.
* @param bool|int|string $idGoal The goal ID to filter by, or a special ecommerce goal identifier.
* @param array|string $columns Array of metrics to fetch: nb_conversions, conversion_rate, revenue.
* @param bool $showAllGoalSpecificMetrics whether to show all goal specific metrics when no goal is set
* @param bool $compare If true, leaves metrics unformatted until the queued formatter runs later.
*
* @return DataTable
* @return DataTable|DataTable\Map
*/
public function get($idSite, $period, $date, $segment = false, $idGoal = false, $columns = array(), $showAllGoalSpecificMetrics = false, $compare = false)
{
Expand Down Expand Up @@ -599,6 +677,24 @@
* any segment by default. This method is deprecated from the API as it is only there to make the implementation of
* the actual {@link get()} method easy.
*
* @param int|string|int[] $idSite Website ID(s) to query.
* - Single site ID (e.g. 1)
* - Multiple site IDs (e.g. [1, 4, 5])
* - Comma-separated list ("1,4,5") or "all"
* @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 $segment Custom segment to filter the report.
* Example: "referrerName==example.com"
* Supports AND (;) and OR (,) operators.
* @param bool|int|string $idGoal The goal ID to filter by, or a special ecommerce goal identifier.
* @param array|string $columns Array of metrics to fetch: nb_conversions, conversion_rate, revenue.
* @param bool $showAllGoalSpecificMetrics Whether to show all goal-specific metrics when no goal is set.
*
* @return DataTable
*
* @deprecated
* @internal
*/
Expand Down Expand Up @@ -792,12 +888,20 @@
* Gets a DataTable that maps ranges of days to the number of conversions that occurred
* within those ranges, for the specified site, date range, segment and goal.
*
* @param int $idSite The site to select data from.
* @param string $period The period type.
* @param string $date The date type.
* @param string|bool $segment The segment.
* @param int|bool $idGoal The id of the goal to get data for. If this is set to false,
* data for every goal that belongs to $idSite is returned.
* @param int|string|int[] $idSite Website ID(s) to query.
* - Single site ID (e.g. 1)
* - Multiple site IDs (e.g. [1, 4, 5])
* - Comma-separated list ("1,4,5") or "all"
* @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 $segment Custom segment to filter the report.
* Example: "referrerName==example.com"
* Supports AND (;) and OR (,) operators.
* @param int|bool|string $idGoal The goal ID to get data for. If false, returns data for every goal that
* belongs to $idSite.
*
* @return false|DataTable
*/
Expand Down Expand Up @@ -825,12 +929,20 @@
* Gets a DataTable that maps ranges of visit counts to the number of conversions that
* occurred on those visits for the specified site, date range, segment and goal.
*
* @param int $idSite The site to select data from.
* @param string $period The period type.
* @param string $date The date type.
* @param string|bool $segment The segment.
* @param int|bool $idGoal The id of the goal to get data for. If this is set to false,
* data for every goal that belongs to $idSite is returned.
* @param int|string|int[] $idSite Website ID(s) to query.
* - Single site ID (e.g. 1)
* - Multiple site IDs (e.g. [1, 4, 5])
* - Comma-separated list ("1,4,5") or "all"
* @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 $segment Custom segment to filter the report.
* Example: "referrerName==example.com"
* Supports AND (;) and OR (,) operators.
* @param int|bool|string $idGoal The goal ID to get data for. If false, returns data for every goal that
* belongs to $idSite.
*
* @return bool|DataTable
*/
Expand Down
Loading