API Reference

VisitDimension

Piwik\Plugin\Dimension\

VisitDimension

Since Matomo 2.5.0

Defines a new visit dimension that records any visit related information during tracking.

You can record any visit information by implementing one of the following events: onNewVisit(), onExistingVisit(), onConvertedVisit() or onAnyGoalConversion(). By defining a $columnName and $columnType a new column will be created in the database (table log_visit) automatically and the values you return in the previous mentioned events will be saved in this column.

You can create a new dimension using the console command ./console generate:dimension.

Properties

This abstract class defines the following properties:

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

$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()

Get all visit dimensions that are defined by all activated plugins.

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.

getRequiredVisitFields()

Sometimes you may want to make sure another dimension is executed before your dimension so you can persist this dimensions' value depending on the value of other dimensions. You can do this by defining an array of dimension names. If you access any value of any other column within your events, you should require them here.

Otherwise those values may not be available.

Signature

  • It returns a array value.

onNewVisit()

The onNewVisit method is triggered when a new visitor is detected. This means you can define an initial value for this user here. By returning boolean false no value will be saved. Once the user makes another action the event "onExistingVisit" is executed. Meaning for each visitor this method is executed once.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) —

    • $visitor (Piwik\Tracker\Visitor) —

    • $action (Piwik\Tracker\Action|null) —

  • Returns: mixed|false —

onExistingVisit()

The onExistingVisit method is triggered when a visitor was recognized meaning it is not a new visitor.

You can overwrite any previous value set by the event onNewVisit by implementing this event. By returning boolean false no value will be updated.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) —

    • $visitor (Piwik\Tracker\Visitor) —

    • $action (Piwik\Tracker\Action|null) —

  • Returns: mixed|false —

onConvertedVisit()

This event is executed shortly after onNewVisit or onExistingVisit in case the visitor converted a goal.

Usually this event is not needed and you can simply remove this method therefore. An example would be for instance to persist the last converted action url. Return boolean false if you do not want to change the current value.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) —

    • $visitor (Piwik\Tracker\Visitor) —

    • $action (Piwik\Tracker\Action|null) —

  • Returns: mixed|false —

onAnyGoalConversion()

By implementing this event you can persist a value to the log_conversion table in case a conversion happens.

The persisted value will be logged along the conversion and will not be changed afterwards. This allows you to generate reports that shows for instance which url was called how often for a specific conversion. Once you implement this event and a $columnType is defined a column in the log_conversion MySQL table will be created automatically.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) —

    • $visitor (Piwik\Tracker\Visitor) —

    • $action (Piwik\Tracker\Action|null) —

  • Returns: mixed|false —

shouldForceNewVisit()

This hook is executed by the tracker when determining if an action is the start of a new visit or part of an existing one. Derived classes can use it to force new visits based on dimension data.

For example, the Campaign dimension in the Referrers plugin will force a new visit if the campaign information for the current action is different from the last.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) — The current tracker request information.
    • $visitor (Piwik\Tracker\Visitor) — The information for the currently recognized visitor.
    • $action (Piwik\Tracker\Action|null) — The current action information (if any).

  • Returns: bool — Return true to force a visit, false if otherwise.

sortStaticListByUsage()

Sort a key => value array descending by the number of occurrences of the key in the supplied table and column

Signature

  • It accepts the following parameter(s):

    • $array (array) — Key value array
    • $table (DataTable) — Datatable from which to count occurrences
    • $keyColumn (string) — Column in the datatable to match against the array key
    • $maxValuesToReturn (int) — Limit the return array to this number of elements

  • Returns: array — An array of values from the source array sorted by most occurrences, descending