Piwik\Plugin\
Since Matomo 2.5.0
Creates a new segment that can be used for instance within the \Piwik\Columns\Dimension::configureSegment() method.
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"');
This class defines the following properties:
$dimensionDimension value.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.setSuggestedValuesApi() — Set callback which will be executed when user will call for suggested values for segment.setNeedsMostFrequentValues()setPermission() — You can restrict the access to this segment by passing a boolean false.setIsInternal() — Sets whether the segment is for internal use only and should not be visible in the UI or in API metadata output.isInternal() — Gets whether the segment is for internal use only and should not be visible in the UI or in API metadata output.init()Here you can initialize this segment and set any default values. It is called directly after the object is created.
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."
It accepts the following parameter(s):
$acceptedValues (string) —It does not return anything or a mixed result.
setCategory()Set (overwrite) the category this segment belongs to. It should be a translation key such as 'General_Actions' or 'General_Visit'.
It accepts the following parameter(s):
$category (string) —It does not return anything or a mixed result.
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'.
It accepts the following parameter(s):
$name (string) —It does not return anything or a mixed result.
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.
It accepts the following parameter(s):
$segment (string) —It does not return anything or a mixed result.
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 specifying 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 (formerly Piwik) assumes the segment sub-string will not match any visitor.
It accepts the following parameter(s):
$sqlFilter (callable) —It does not return anything or a mixed result.
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().
It accepts the following parameter(s):
$sqlFilterValue (string|array) —It does not return anything or a mixed result.
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.
It accepts the following parameter(s):
$sqlSegment (string) —It does not return anything or a mixed result.
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.
It accepts the following parameter(s):
$segments (array) —It does not return anything or a mixed result.
setType()Set (overwrite) the type of this segment which is usually either a 'dimension' or a 'metric'.
$type (string) —
See constants TYPE_*getSegment()Returns the name of this segment as it should appear in segment expressions.
string value.setSuggestedValuesCallback()Set callback which will be executed when user will call for suggested values for segment.
It accepts the following parameter(s):
$suggestedValuesCallback (callable) —It does not return anything or a mixed result.
setSuggestedValuesApi()Set callback which will be executed when user will call for suggested values for segment.
It accepts the following parameter(s):
$suggestedValuesApi (string) —It does not return anything or a mixed result.
setNeedsMostFrequentValues()It accepts the following parameter(s):
$value (bool) —It does not return anything or a mixed result.
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());
It accepts the following parameter(s):
$permission (bool) —It does not return anything or a mixed result.
setIsInternal()Sets whether the segment is for internal use only and should not be visible in the UI or in API metadata output.
These types of segments are, for example, used in unions for other segments, but have no value to users.
It accepts the following parameter(s):
$value (bool) —It does not return anything or a mixed result.
isInternal()Gets whether the segment is for internal use only and should not be visible in the UI or in API metadata output.
These types of segments are, for example, used in unions for other segments, but have no value to users.
bool value.