Piwik\

Segment

Limits the set of visits Matomo (formerly Piwik) uses when aggregating analytics data.

A segment is a condition used to filter visits. They can, for example, select visits that have a specific browser or come from a specific country, or both.

Plugins that aggregate data stored in Matomo can support segments by using this class when generating aggregation SQL queries.

Examples

Basic usage

$idSites = array(1,2,3);
$segmentStr = "browserCode==ff;countryCode==CA";
$segment = new Segment($segmentStr, $idSites);

$query = $segment->getSelectQuery(
    $select = "table.col1, table2.col2",
    $from = array("table", "table2"),
    $where = "table.col3 = ?",
    $bind = array(5),
    $orderBy = "table.col1 DESC",
    $groupBy = "table2.col2"
);

Db::fetchAll($query['sql'], $query['bind']);

Creating a null segment

$idSites = array(1,2,3);
$segment = new Segment('', $idSites);
// $segment->getSelectQuery will return a query that selects all visits

Methods

The class defines the following methods:

• __construct() — Constructor.
• isAvailable() — Checks if the provided segmentCondition is valid and available for the given idSites
• getSegmentExpression() — Returns the segment expression.
• isEmpty() — Returns true if the segment is empty, false if otherwise.
• willBeArchived() — Detects whether the Matomo instance is configured to be able to archive this segment.
• getString() — Returns the segment condition.
• getHash() — Returns a hash of the segment condition, or the empty string if the segment condition is empty.
• getSegmentHash()
• getSelectQuery() — Extend an SQL query that aggregates data over one of the 'log_' tables with segment expressions.
• __toString() — Returns the segment string.
• combine() — Combines this segment with another segment condition, if the segment condition is not already in the segment.
• getStoredSegmentName()
• getOriginalString()

__construct()

Constructor.

When using segments that contain a != or !@ condition on a non visit dimension (e.g. action, conversion, ...) it is needed to use a subquery to get correct results. To avoid subqueries that fetch too many data it's required to set a startDate and/or an endDate in this case. That date will be used to limit the subquery (along with possibly given idSites). If no startDate and endDate is given for such a segment it will generate a query that directly joins the according tables, but trigger a php warning as results might be incorrect.

Signature

• It accepts the following parameter(s):
  • $segmentCondition (string) — The segment condition, eg, 'browserCode=ff;countryCode=CA'.
  • $idSites (array) — The list of sites the segment will be used with. Some segments are dependent on the site, such as goal segments.
  • $startDate (Date|null) — start date used to limit subqueries
  • $endDate (Date|null) — end date used to limit subqueries
• It throws one of the following exceptions:
  • ``

isAvailable()

Checks if the provided segmentCondition is valid and available for the given idSites

Signature

• It accepts the following parameter(s):

  • $segmentCondition (string) —

  • $idSites (array) —

• It returns a bool value.

getSegmentExpression()

Returns the segment expression.

Signature

• It returns a Piwik\Segment\SegmentExpression value.

isEmpty()

Returns true if the segment is empty, false if otherwise.

Signature

• It does not return anything or a mixed result.

willBeArchived()

Detects whether the Matomo instance is configured to be able to archive this segment. It checks whether the segment will be either archived via browser or cli archiving. It does not check if the segment has been archived. If you want to know whether the segment has been archived, the actual report data needs to be requested.

This method does not take any date/period into consideration. Meaning a Matomo instance might be able to archive this segment in general, but not for a certain period if eg the archiving of range dates is disabled.

Signature

• It returns a bool value.

getString()

Returns the segment condition.

Signature

• It returns a string value.

getHash()

Returns a hash of the segment condition, or the empty string if the segment condition is empty.

Signature

• It returns a string value.

getSegmentHash()

Signature

• It accepts the following parameter(s):

  • $definition

• It does not return anything or a mixed result.

getSelectQuery()

Extend an SQL query that aggregates data over one of the 'log_' tables with segment expressions.

Signature

• It accepts the following parameter(s):

  • $select

  • $from

  • $where

  • $bind

  • $orderBy

  • $groupBy

  • $limit

  • $offset

  • $forceGroupBy

• Returns: array — The entire select query.

__toString()

Returns the segment string.

Signature

• It returns a string value.

combine()

Combines this segment with another segment condition, if the segment condition is not already in the segment.

The combination is naive in that it does not take order of operations into account.

Signature

• It accepts the following parameter(s):

  • $segment (string) —

  • $operator (string) — The operator to use. Should be either SegmentExpression::AND_DELIMITER or SegmentExpression::OR_DELIMITER.

  • $segmentCondition (string) — The segment condition to add.
• It returns a string value.
• It throws one of the following exceptions:
  • Exception

getStoredSegmentName()

Signature

• It accepts the following parameter(s):

  • $idSite

• It does not return anything or a mixed result.

getOriginalString()

Signature

• It does not return anything or a mixed result.