Hugging Face's logo

Spaces:
Leon4gr45
/
matomo
Paused

App Files Community
matomo / core /Plugin /Dimension /VisitDimension.php
Leon4gr45's picture
Leon4gr45
Upload source files chunk 36
f8ce8bb verified
Raw History Blame Contribute Delete
13.6 kB
<?php
/**
* Matomo - free/libre analytics platform
*
* @link https://matomo.org
* @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
*/
namespace Piwik\Plugin\Dimension;
use Piwik\CacheId;
use Piwik\Cache as PiwikCache;
use Piwik\Columns\Dimension;
use Piwik\Common;
use Piwik\DataTable;
use Piwik\Db;
use Piwik\DbHelper;
use Piwik\Plugin\Manager as PluginManager;
use Piwik\Tracker\Request;
use Piwik\Tracker\Visitor;
use Piwik\Tracker\Action;
use Piwik\Plugin;
use Exception;
/**
* 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: {@link onNewVisit()},
* {@link onExistingVisit()}, {@link onConvertedVisit()} or {@link onAnyGoalConversion()}. By defining a
* {@link $columnName} and {@link $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`.
*
* @api
* @since 2.5.0
*/
abstract class VisitDimension extends Dimension
{
public const INSTALLER_PREFIX = 'log_visit.';
protected $dbTableName = 'log_visit';
protected $category = 'General_Visitors';
public function install()
{
if (empty($this->columnType) || empty($this->columnName)) {
return array();
}
$changes = array(
$this->dbTableName => array("ADD COLUMN `$this->columnName` $this->columnType"),
);
if ($this->isHandlingLogConversion()) {
$changes['log_conversion'] = array("ADD COLUMN `$this->columnName` $this->columnType");
}
return $changes;
}
/**
* @see ActionDimension::update()
* @return array
* @ignore
*/
public function update()
{
if (!$this->columnType) {
return array();
}
$conversionColumns = DbHelper::getTableColumns(Common::prefixTable('log_conversion'));
$changes = array();
$changes[$this->dbTableName] = array("MODIFY COLUMN `$this->columnName` $this->columnType");
$handlingConversion = $this->isHandlingLogConversion();
$hasConversionColumn = array_key_exists($this->columnName, $conversionColumns);
if ($hasConversionColumn && $handlingConversion) {
$changes['log_conversion'] = array("MODIFY COLUMN `$this->columnName` $this->columnType");
} elseif (!$hasConversionColumn && $handlingConversion) {
$changes['log_conversion'] = array("ADD COLUMN `$this->columnName` $this->columnType");
} elseif ($hasConversionColumn && !$handlingConversion) {
$changes['log_conversion'] = array("DROP COLUMN `$this->columnName`");
}
return $changes;
}
/**
* @return string
* @ignore
*/
public function getVersion()
{
return $this->columnType . $this->isHandlingLogConversion();
}
private function isHandlingLogConversion()
{
if (empty($this->columnName) || empty($this->columnType)) {
return false;
}
return $this->hasImplementedEvent('onAnyGoalConversion');
}
/**
* Uninstalls the dimension if a {@link $columnName} and {@link columnType} is set. In case you perform any custom
* actions during {@link 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.
* @throws Exception
* @api
*/
public function uninstall()
{
if (empty($this->columnName) || empty($this->columnType)) {
return;
}
try {
$sql = "ALTER TABLE `" . Common::prefixTable($this->dbTableName) . "` DROP COLUMN `$this->columnName`";
Db::exec($sql);
} catch (Exception $e) {
if (!Db::get()->isErrNo($e, '1091')) {
throw $e;
}
}
try {
if (!$this->isHandlingLogConversion()) {
return;
}
$sql = "ALTER TABLE `" . Common::prefixTable('log_conversion') . "` DROP COLUMN `$this->columnName`";
Db::exec($sql);
} catch (Exception $e) {
if (!Db::get()->isErrNo($e, '1091')) {
throw $e;
}
}
}
/**
* 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.
* @return array
* @api
*/
public function getRequiredVisitFields()
{
return array();
}
/**
* 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.
*
* @param Action|null $action
* @return mixed|false
* @api
*/
public function onNewVisit(Request $request, Visitor $visitor, $action)
{
return false;
}
/**
* 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.
*
* @param Action|null $action
* @return mixed|false
* @api
*/
public function onExistingVisit(Request $request, Visitor $visitor, $action)
{
return false;
}
/**
* 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.
*
* @param Action|null $action
* @return mixed|false
* @api
*/
public function onConvertedVisit(Request $request, Visitor $visitor, $action)
{
return false;
}
/**
* 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.
*
* @param Action|null $action
* @return mixed|false
* @api
*/
public function onAnyGoalConversion(Request $request, Visitor $visitor, $action)
{
return false;
}
/**
* 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.
*
* @param Request $request The current tracker request information.
* @param Visitor $visitor The information for the currently recognized visitor.
* @param Action|null $action The current action information (if any).
* @return bool Return true to force a visit, false if otherwise.
* @api
*/
public function shouldForceNewVisit(Request $request, Visitor $visitor, ?Action $action = null)
{
return false;
}
/**
* Get all visit dimensions that are defined by all activated plugins.
* @return VisitDimension[]
*/
public static function getAllDimensions()
{
$cacheId = CacheId::pluginAware('VisitDimensions');
$cache = PiwikCache::getTransientCache();
if (!$cache->contains($cacheId)) {
$plugins = PluginManager::getInstance()->getPluginsLoadedAndActivated();
$instances = array();
foreach ($plugins as $plugin) {
foreach (self::getDimensions($plugin) as $instance) {
$instances[] = $instance;
}
}
$instances = self::sortDimensions($instances);
$cache->save($cacheId, $instances);
}
return $cache->fetch($cacheId);
}
/**
* @ignore
* @param VisitDimension[] $dimensions
*/
public static function sortDimensions($dimensions)
{
$sorted = array();
$exists = array();
// we first handle all the once without dependency
foreach ($dimensions as $index => $dimension) {
$fields = $dimension->getRequiredVisitFields();
if (empty($fields)) {
$sorted[] = $dimension;
$exists[] = $dimension->getColumnName();
unset($dimensions[$index]);
}
}
// find circular references
// and remove dependencies whose column cannot be resolved because it is not installed / does not exist / is defined by core
$dependencies = array();
foreach ($dimensions as $dimension) {
$dependencies[$dimension->getColumnName()] = $dimension->getRequiredVisitFields();
}
foreach ($dependencies as $column => $fields) {
foreach ($fields as $key => $field) {
if (empty($dependencies[$field]) && !in_array($field, $exists)) {
// we cannot resolve that dependency as it does not exist
unset($dependencies[$column][$key]);
} elseif (!empty($dependencies[$field]) && in_array($column, $dependencies[$field])) {
throw new Exception("Circular reference detected for required field $field in dimension $column");
}
}
}
$count = 0;
while (count($dimensions) > 0) {
$count++;
if ($count > 1000) {
foreach ($dimensions as $dimension) {
$sorted[] = $dimension;
}
break; // to prevent an endless loop
}
foreach ($dimensions as $key => $dimension) {
$fields = $dependencies[$dimension->getColumnName()];
if (count(array_intersect($fields, $exists)) === count($fields)) {
$sorted[] = $dimension;
$exists[] = $dimension->getColumnName();
unset($dimensions[$key]);
}
}
}
return $sorted;
}
/**
* Get all visit dimensions that are defined by the given plugin.
* @return VisitDimension[]
* @ignore
*/
public static function getDimensions(Plugin $plugin)
{
$dimensions = $plugin->findMultipleComponents('Columns', '\\Piwik\\Plugin\\Dimension\\VisitDimension');
$instances = array();
foreach ($dimensions as $dimension) {
$instances[] = new $dimension();
}
return $instances;
}
/**
* Sort a key => value array descending by the number of occurrences of the key in the supplied table and column
*
* @param array $array Key value array
* @param DataTable $table Datatable from which to count occurrences
* @param string $keyColumn Column in the datatable to match against the array key
* @param int $maxValuesToReturn Limit the return array to this number of elements
*
* @return array An array of values from the source array sorted by most occurrences, descending
*/
public function sortStaticListByUsage(array $array, DataTable $table, string $keyColumn, int $maxValuesToReturn): array
{
// Convert to multi-dimensional array and count the number of visits for each browser name
foreach ($array as $k => $v) {
$array[$k] = ['count' => 0, 'name' => $v];
}
$array['xx'] = ['count' => 0, 'name' => 'Unknown'];
foreach ($table->getRows() as $row) {
if (isset($row[$keyColumn])) {
if (isset($array[$row[$keyColumn]])) {
$array[$row[$keyColumn]]['count']++;
} else {
$array['xx']['count']++;
}
}
}
// Sort by most visits descending
uasort($array, function ($a, $b) {
return $a <=> $b;
});
$array = array_reverse($array, true);
// Flatten and limit the return array
$flat = [];
$i = 0;
foreach ($array as $k => $v) {
$flat[$k] = $v['name'];
$i++;
if ($i == ($maxValuesToReturn)) {
break;
}
}
return array_values($flat);
}
}