Piwik\Plugin\

Segment

Since Matomo (formerly Piwik) 2.5.0

Creates a new segment that can be used for instance within the \Piwik\Columns\Dimension::configureSegment() method.

Make sure to set at least the following values: setName(), setSegment(), setSqlSegment(), setType() and setCategory(). If you are using a segment in the context of a dimension the type and the SQL segment is usually set for you automatically.

Example:

$segment = new \Piwik\Plugin\Segment();
$segment->setType(\Piwik\Plugin\Segment::TYPE_DIMENSION);
$segment->setName('General_EntryKeyword');
$segment->setCategory('General_Visit');
$segment->setSegment('entryKeyword');
$segment->setSqlSegment('log_visit.entry_keyword');
$segment->setAcceptedValues('Any keywords people search for on your website such as "help" or "imprint"');

Constants

This class defines the following constants:

TYPE_DIMENSION

Can be used along with setType().

TYPE_METRIC

Can be used along with setType().

Methods

The class defines the following methods:

  • init() — Here you can initialize this segment and set any default values.
  • setAcceptedValues() ash; Here you should explain which values are accepted/useful for your segment, for example: "1, 2, 3, etc." or "comcast.net, proxad.net, etc.".
  • setCategory() — Set (overwrite) the category this segment belongs to.
  • setName() — Set (overwrite) the segment display name.
  • setSegment() — Set (overwrite) the name of the segment.
  • setSqlFilter() — Sometimes you want users to set values that differ from the way they are actually stored.
  • setSqlFilterValue() ash; Similar to setSqlFilter() you can map a given segment value to another value.
  • setSqlSegment() — Defines to which column in the MySQL database the segment belongs: 'mytablename.mycolumnname'.
  • setUnionOfSegments() — Set a list of segments that should be used instead of fetching the values from a single column.
  • setType() — Set (overwrite) the type of this segment which is usually either a 'dimension' or a 'metric'.
  • getSegment() — Returns the name of this segment as it should appear in segment expressions.
  • setSuggestedValuesCallback() — Set callback which will be executed when user will call for suggested values for segment.
  • setPermission() — You can restrict the access to this segment by passing a boolean false.

init()

Here you can initialize this segment and set any default values.

It is called directly after the object is created.

Signature

  • It does not return anything.

setAcceptedValues()

Here you should explain which values are accepted/useful for your segment, for example: "1, 2, 3, etc." or "comcast.net, proxad.net, etc.".

If the value needs any special encoding you should mention this as well. For example "Any URL including protocol. The URL must be URL encoded."

Signature

  • It accepts the following parameter(s):

    • $acceptedValues (string) —
  • It does not return anything.

setCategory()

Set (overwrite) the category this segment belongs to.

It should be a translation key such as 'General_Actions' or 'General_Visit'.

Signature

  • It accepts the following parameter(s):

    • $category (string) —
  • It does not return anything.

setName()

Set (overwrite) the segment display name.

This name will be visible in the API and the UI. It should be a translation key such as 'Actions_ColumnEntryPageTitle' or 'Resolution_ColumnResolution'.

Signature

  • It accepts the following parameter(s):

    • $name (string) —
  • It does not return anything.

setSegment()

Set (overwrite) the name of the segment.

The name should be lower case first and has to be unique. The segment name defined here needs to be set in the URL to actually apply this segment. Eg if the segment is 'searches' you need to set "&segment=searches>0" in the UI.

Signature

  • It accepts the following parameter(s):

    • $segment (string) —
  • It does not return anything.

setSqlFilter()

Sometimes you want users to set values that differ from the way they are actually stored.

For instance if you want to allow to filter by any URL than you might have to resolve this URL to an action id. Or a country name maybe has to be mapped to a 2 letter country code. You can do this by specifing either a callable such as array('Classname', 'methodName') or by passing a closure. There will be four values passed to the given closure or callable: string $valueToMatch, string $segment (see setSegment()), string $matchType (eg SegmentExpression::MATCH_EQUAL or any other match constant of this class) and $segmentName.

If the closure returns NULL, then Matomo assumes the segment sub-string will not match any visitor.

Signature

  • It accepts the following parameter(s):

  • It does not return anything.

setSqlFilterValue()

Similar to setSqlFilter() you can map a given segment value to another value.

For instance you could map "new" to 0, 'returning' to 1 and any other value to '2'. You can either define a callable or a closure. There will be only one value passed to the closure or callable which contains the value a user has set for this segment. This callback is called shortly before setSqlFilter().

Signature

  • It accepts the following parameter(s):

    • $sqlFilterValue (string|array) —
  • It does not return anything.

setSqlSegment()

Defines to which column in the MySQL database the segment belongs: 'mytablename.mycolumnname'.

Eg 'log_visit.idsite'. When a segment is applied the given or filtered value will be compared with this column.

Signature

  • It accepts the following parameter(s):

    • $sqlSegment (string) —
  • It does not return anything.

setUnionOfSegments()

Set a list of segments that should be used instead of fetching the values from a single column.

All set segments will be applied via an OR operator.

Signature

  • It accepts the following parameter(s):

    • $segments (array) —
  • It does not return anything.

setType()

Set (overwrite) the type of this segment which is usually either a 'dimension' or a 'metric'.

Signature

  • It accepts the following parameter(s):
    • $type (string) — See constansts TYPE_*
  • It does not return anything.

getSegment()

Returns the name of this segment as it should appear in segment expressions.

Signature

  • It returns a string value.

setSuggestedValuesCallback()

Set callback which will be executed when user will call for suggested values for segment.

Signature

  • It accepts the following parameter(s):

    • $suggestedValuesCallback (callable) —
  • It does not return anything.

setPermission()

You can restrict the access to this segment by passing a boolean false.

For instance if you want to make a certain segment only available to users having super user access you could do the following: $segment->setPermission(Piwik::hasUserSuperUserAccess());

Signature

  • It accepts the following parameter(s):

    • $permission (bool) —
  • It does not return anything.