Piwik\Plugin\Dimension\

VisitDimension

Since Piwik 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.

Constants

This abstract class defines the following constants:

TYPE_DIMENSION

Can be used along with setType().

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 conifugred). 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 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

  • Its type is not specified.

$namePlural

Translation key for name plural

Signature

  • Its type is not specified.

$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

  • Its type is not specified.

$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

  • Its type is not specified.

$sqlSegment

Defines to which column in the MySQL database the segment belongs (if one is conifugred).

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 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 Piwik assumes the segment sub-string will not match any visitor.

Signature

  • Its type is not specified.

$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

  • Its type is not specified.

$allowAnonymous

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

Signature

  • Its type is not specified.

$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

  • Its type is not specified.

Methods

The abstract class defines the following methods:

getDbColumnJoin()

To be implemented when a column references another column

Signature

  • It does not return anything.

getDbDiscriminator()

Signature

  • It does not return anything.

getEnumColumnValues()

To be implemented when a column represents an enum.

Signature

  • It does not return anything.

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.
  • 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 does not return anything.

isAnonymousAllowed()

Defines whether an anonymous user is allowed to view this dimension

Signature

  • It does not return anything.

setSqlSegment()

Sets (overwrites) the SQL segment

Signature

  • It accepts the following parameter(s):

    • $segment (Piwik\Columns\$segment) —
  • It does not return anything.

setType()

Sets (overwrites the dimension type)

Signature

  • It accepts the following parameter(s):

    • $type (Piwik\Columns\$type) —
  • It does not return anything.

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 does not return anything.

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 does not return anything.

configureMetrics()

Configures metrics for this dimension.

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

Signature

addSegment()

Adds a new segment.

It automatically sets the SQL segment depending on the column name in case none is set already.

See Also

  • \Piwik\Columns\Dimension::addSegment()

Signature

  • It accepts the following parameter(s):

  • It does not return anything.

getSegmentName()

Returns the name of the segment that this dimension defines

Signature

  • It does not return anything.

getSqlSegment()

Returns a sql segment expression for this dimension.

Signature

  • It does not return anything.

getDbTableName()

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

Signature

  • It does not return anything.

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.

factory()

Creates a Dimension instance from a string ID (see getId()).

Signature

  • It accepts the following parameter(s):

    • $dimensionId (string) — See getId().
  • Returns: Dimension|null — The created instance or null if there is no Dimension for $dimensionId or if the plugin that contains the Dimension is not loaded.

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 does not return anything.

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|Piwik\Plugin\Dimension\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 implemting 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|Piwik\Plugin\Dimension\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|Piwik\Plugin\Dimension\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|Piwik\Plugin\Dimension\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) — The current action information (if any).
  • Returns: bool — Return true to force a visit, false if otherwise.