API Reference

Dimension

Piwik\Columns\

Dimension

Since Matomo 3.1.0

Properties

This abstract class defines the following properties:

  • $columnName — This will be the name of the column in the database table if a $columnType is specified.
  • $columnType — If a columnType is defined, we will create a column in the MySQL table having this type.
  • $type — Defines what kind of data type this dimension holds.
  • $namePlural — Translation key for name plural
  • $segmentName — By defining a segment name a user will be able to filter their visitors by this column.
  • $suggestedValuesCallback — Sets a callback which will be executed when user will call for suggested values for segment.
  • $acceptValues 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.".
  • $sqlSegment — Defines to which column in the MySQL database the segment belongs (if one is configured).
  • $sqlFilter — Interesting when specifying a segment.
  • $sqlFilterValue ash; Similar to $sqlFilter you can map a given segment value to another value.
  • $allowAnonymous — Defines whether this dimension (and segment based on this dimension) is available to anonymous users.
  • $dbTableName — The name of the database table this dimension refers to
  • $metricId — By default the metricId is automatically generated based on the dimensionId.

$columnName

This will be the name of the column in the database table if a $columnType is specified.

Signature

  • It is a string value.

$columnType

If a columnType is defined, we will create a column in the MySQL table having this type. Please make sure MySQL understands this type. Once you change the column type the Matomo (formerly Piwik) platform will notify the user to perform an update which can sometimes take a long time so be careful when choosing the correct column type.

Signature

  • It is a string value.

$type

Defines what kind of data type this dimension holds. By default the type is auto-detected based on $columnType but sometimes it may be needed to correct this value. Depending on this type, a dimension will be formatted differently for example.

Signature

  • It is a string value.

$namePlural

Translation key for name plural

Signature

  • It is a string value.

$segmentName

By defining a segment name a user will be able to filter their visitors by this column. If you do not want to define a segment for this dimension, simply leave the name empty.

Signature

  • Its type is not specified.

$suggestedValuesCallback

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

Signature

  • It is a callable value.

$acceptValues

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 is a string value.

$sqlSegment

Defines to which column in the MySQL database the segment belongs (if one is configured). Defaults to $this.dbTableName . '.'. $this.columnName but you can customize it eg like HOUR(log_visit.visit_last_action_time).

Signature

  • Its type is not specified.

$sqlFilter

Interesting when specifying a segment. Sometimes you want users to set segment 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 assumes the segment sub-string will not match any visitor.

Signature

  • It can be one of the following types:

$sqlFilterValue

Similar to $sqlFilter 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.

Signature

  • It can be one of the following types:
    • string
    • array

$allowAnonymous

Defines whether this dimension (and segment based on this dimension) is available to anonymous users.

Signature

  • It is a bool value.

$dbTableName

The name of the database table this dimension refers to

Signature

  • It is a string value.

$metricId

By default the metricId is automatically generated based on the dimensionId. This might sometimes not be as readable and quite long. If you want more expressive metric names like nb_visits compared to nb_corehomevisitid, you can eg set a metricId visit.

Signature

  • It is a string value.

Methods

The abstract class defines the following methods:

getDbColumnJoin()

To be implemented when a column references another column

Signature

  • Returns: Join|null —

getDbDiscriminator()

Signature

getEnumColumnValues()

To be implemented when a column represents an enum.

Signature

  • It returns a array value.

getMetricId()

Get the metricId which is used to generate metric names based on this dimension.

Signature

  • It returns a string value.

install()

Installs the action dimension in case it is not installed yet. The installation is already implemented based on the $columnName and $columnType. If you want to perform additional actions beside adding the column to the database - for instance adding an index - you can overwrite this method. We recommend to call this parent method to get the minimum required actions and then add further custom actions since this makes sure the column will be installed correctly. We also recommend to change the default install behavior only if really needed. FYI: We do not directly execute those alter table statements here as we group them together with several other alter table statements do execute those changes in one step which results in a faster installation. The column will be added to the log_link_visit_action MySQL table.

Example:

public function install()
{
$changes = parent::install();
$changes['log_link_visit_action'][] = "ADD INDEX index_idsite_servertime ( idsite, server_time )";

return $changes;
}

Signature

  • Returns: array — An array containing the table name as key and an array of MySQL alter table statements that should be executed on the given table. Example:
array(
'log_link_visit_action' => array("ADD COLUMN `$this->columnName` $this->columnType", "ADD INDEX ...")
);

uninstall()

Uninstalls the dimension if a $columnName and columnType is set. In case you perform any custom actions during install() - for instance adding an index - you should make sure to undo those actions by overwriting this method. Make sure to call this parent method to make sure the uninstallation of the column will be done.

Signature

  • It does not return anything or a mixed result.
  • It throws one of the following exceptions:

getCategoryId()

Returns the ID of the category (typically a translation key).

Signature

  • It returns a string value.

getName()

Returns the translated name of this dimension which is typically in singular.

Signature

  • It returns a string value.

getNamePlural()

Returns a translated name in plural for this dimension.

Signature

  • It returns a string value.

isAnonymousAllowed()

Defines whether an anonymous user is allowed to view this dimension

Signature

  • It returns a bool value.

setSqlSegment()

Sets (overwrites) the SQL segment

Signature

  • It accepts the following parameter(s):

    • $segment

  • It does not return anything or a mixed result.

setType()

Sets (overwrites the dimension type)

Signature

  • It accepts the following parameter(s):

    • $type

  • It does not return anything or a mixed result.

groupValue()

A dimension should group values by using this method. Otherwise the same row may appear several times.

Signature

  • It accepts the following parameter(s):

    • $value (mixed) —

    • $idSite (int) —

  • It returns a mixed value.

formatValue()

Formats the dimension value. By default, the dimension is formatted based on the set dimension type.

Signature

  • It accepts the following parameter(s):

    • $value (mixed) —

    • $idSite (int) —

    • $formatter (Formatter) —

  • It returns a mixed value.

configureSegments()

Overwrite this method to configure segments. To do so just create an instance of a Segment class, configure it and call the addSegment() method. You can add one or more segments for this dimension. Example:

$segment = new Segment();
$segment->setSegment('exitPageUrl');
$segment->setName('Actions_ColumnExitPageURL');
$segment->setCategory('General_Visit');
$segmentsList->addSegment($segment);

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

  • It throws one of the following exceptions:

configureMetrics()

Configures metrics for this dimension.

For certain dimension types, some metrics will be added automatically.

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

getSegmentName()

Returns the name of the segment that this dimension defines

Signature

  • It returns a string value.

getSqlSegment()

Returns a sql segment expression for this dimension.

Signature

  • It returns a string value.

getDbTableName()

Returns the name of the database table this dimension belongs to.

Signature

  • It returns a string value.

getId()

Returns a unique string ID for this dimension. The ID is built using the namespaced class name of the dimension, but is modified to be more human readable.

Signature

  • Returns: string — eg, "Referrers.Keywords"
  • It throws one of the following exceptions:
    • Exception — if the plugin and simple class name of this instance cannot be determined. This would only happen if the dimension is located in the wrong directory.

getAllDimensions()

Gets an instance of all available visit, action and conversion dimension.

Signature

getDimensions()

Signature

  • It accepts the following parameter(s):

  • It does not return anything or a mixed result.

getRemovedDimensions()

Returns a list of dimension class names that have been removed from core over time

Signature

  • It returns a string[] value.

getModule()

Returns the name of the plugin that contains this Dimension.

Signature

  • It returns a string value.
  • It throws one of the following exceptions:
    • Exception — if the Dimension is not located within a Plugin module.

getType()

Returns the type of the dimension which defines what kind of value this dimension stores.

Signature

  • It returns a string value.