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.
  • 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.
  • 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.

__construct()

Constructor.

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.

getSegmentExpression()

Returns the segment expression.

Signature

  • It does not return anything.

isEmpty()

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

Signature

  • It does not return anything.

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.

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

  • Returns: string — 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: