diff options
author | Thomas Steur <thomas.steur@googlemail.com> | 2014-07-18 14:43:49 +0400 |
---|---|---|
committer | Thomas Steur <thomas.steur@googlemail.com> | 2014-07-18 14:43:49 +0400 |
commit | 9df00a69dc93f29bd9a8efbe8bb239a3b9e07886 (patch) | |
tree | 8e5bf94de20ba0a3b065ea220daa906a2690f89a /core/Plugin/Dimension | |
parent | 1fedbbd0b60ad237f8bfa498b342c0322e2e12fe (diff) |
refs #5820 added documentation and improved code
Diffstat (limited to 'core/Plugin/Dimension')
-rw-r--r-- | core/Plugin/Dimension/ActionDimension.php | 139 | ||||
-rw-r--r-- | core/Plugin/Dimension/ConversionDimension.php | 96 | ||||
-rw-r--r-- | core/Plugin/Dimension/VisitDimension.php | 139 |
3 files changed, 352 insertions, 22 deletions
diff --git a/core/Plugin/Dimension/ActionDimension.php b/core/Plugin/Dimension/ActionDimension.php index ec552e6d8e..0e8814726e 100644 --- a/core/Plugin/Dimension/ActionDimension.php +++ b/core/Plugin/Dimension/ActionDimension.php @@ -13,13 +13,24 @@ use Piwik\Columns\Dimension; use Piwik\Plugin\Manager as PluginManager; use Piwik\Plugin\Segment; use Piwik\Common; +use Piwik\Plugin; use Piwik\Db; use Piwik\Tracker\Action; use Piwik\Tracker\Request; use Piwik\Tracker\Visitor; use Piwik\Translate; +use Exception; /** + * Defines a new action dimension that records any information during tracking for each action. + * + * You can record any action information by implementing one of the following events: {@link onLookupAction()} and + * {@link getActionId()} or {@link onNewAction()}. By defining a {@link $columnName} and {@link $columnType} a new + * column will be created in the database (table `log_link_visit_action`) 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 */ @@ -27,6 +38,36 @@ abstract class ActionDimension extends Dimension { private $tableName = 'log_link_visit_action'; + /** + * Installs the action dimension in case it is not installed yet. The installation is already implemented based on + * the {@link $columnName} and {@link $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; + } + ``` + * + * @return 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 ...") + ); + ``` + * @api + */ public function install() { if (empty($this->columnName) || empty($this->columnType)) { @@ -38,6 +79,24 @@ abstract class ActionDimension extends Dimension ); } + /** + * Updates the action dimension in case the {@link $columnType} has changed. The update is already implemented based + * on the {@link $columnName} and {@link $columnType}. This method is intended not to overwritten by plugin + * developers as it is only supposed to make sure the column has the correct type. Adding additional custom "alter + * table" actions would not really work since they would be executed with every {@link $columnType} change. So + * adding an index here would be executed whenever the columnType changes resulting in an error if the index already + * exists. If an index needs to be added after the first version is released a plugin update class should be + * created since this makes sure it is only executed once. + * + * @return 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("MODIFY COLUMN `$this->columnName` $this->columnType", "DROP COLUMN ...") + ); + ``` + * @ignore + */ public function update() { if (empty($this->columnName) || empty($this->columnType)) { @@ -49,6 +108,14 @@ abstract class ActionDimension extends Dimension ); } + /** + * 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)) { @@ -58,32 +125,77 @@ abstract class ActionDimension extends Dimension try { $sql = "ALTER TABLE `" . Common::prefixTable($this->tableName) . "` DROP COLUMN `$this->columnName`"; Db::exec($sql); - } catch (\Exception $e) { + } catch (Exception $e) { if (!Db::get()->isErrNo($e, '1091')) { throw $e; } } } + /** + * Get the version of the dimension which is used for update checks. + * @return string + * @ignore + */ public function getVersion() { return $this->columnType; } + /** + * If the value you want to save for your dimension is something like a page title or page url, you usually do not + * want to save the raw value over and over again to save bytes in the database. Instead you want to save each value + * once in the log_action table and refer to this value by its ID in the log_link_visit_action table. You can do + * this by returning an action id in "getActionId()" and by returning a value here. If a value should be ignored + * or not persisted just return boolean false. Please note if you return a value here and you implement the event + * "onNewAction" the value will be probably overwritten by the other event. So make sure to implement only one of + * those. + * + * @param Request $request + * @param Action $action + * + * @return false|mixed + * @api + */ public function onLookupAction(Request $request, Action $action) { return false; } /** - * @return string|int - * @throws \Exception in case not implemented + * An action id. The value returned by the lookup action will be associated with this id in the log_action table. + * @return int + * @throws Exception in case not implemented */ public function getActionId() { - throw new \Exception('You need to overwrite the getActionId method in case you implement the onLookupAction method in class: ' . get_class($this)); + throw new Exception('You need to overwrite the getActionId method in case you implement the onLookupAction method in class: ' . get_class($this)); } + /** + * This event is triggered before a new action is logged to the `log_link_visit_action` table. It overwrites any + * looked up action so it makes usually no sense to implement both methods but it sometimes does. You can assign + * any value to the column or return boolan false in case you do not want to save any value. + * + * @param Request $request + * @param Visitor $visitor + * @param Action $action + * + * @return mixed|false + * @api + */ + public function onNewAction(Request $request, Visitor $visitor, Action $action) + { + return false; + } + + /** + * Adds a new segment. It automatically sets the SQL segment depending on the column name in case none is set + * already. + * @see \Piwik\Columns\Dimension::addSegment() + * @param Segment $segment + * @api + */ protected function addSegment(Segment $segment) { $sqlSegment = $segment->getSqlSegment(); @@ -94,7 +206,10 @@ abstract class ActionDimension extends Dimension parent::addSegment($segment); } - /** @return \Piwik\Plugin\Dimension\ActionDimension[] */ + /** + * Get all action dimensions that are defined by all activated plugins. + * @ignore + */ public static function getAllDimensions() { $cache = new PluginAwareStaticCache('ActionDimensions'); @@ -116,8 +231,13 @@ abstract class ActionDimension extends Dimension return $cache->get(); } - /** @return \Piwik\Plugin\Dimension\ActionDimension[] */ - public static function getDimensions(\Piwik\Plugin $plugin) + /** + * Get all action dimensions that are defined by the given plugin. + * @param Plugin $plugin + * @return ActionDimension[] + * @ignore + */ + public static function getDimensions(Plugin $plugin) { $dimensions = $plugin->findMultipleComponents('Columns', '\\Piwik\\Plugin\\Dimension\\ActionDimension'); $instances = array(); @@ -129,9 +249,4 @@ abstract class ActionDimension extends Dimension return $instances; } - public function onNewAction(Request $request, Visitor $visitor, Action $action) - { - return false; - } - } diff --git a/core/Plugin/Dimension/ConversionDimension.php b/core/Plugin/Dimension/ConversionDimension.php index 0df0a02718..4e69e51265 100644 --- a/core/Plugin/Dimension/ConversionDimension.php +++ b/core/Plugin/Dimension/ConversionDimension.php @@ -19,8 +19,20 @@ use Piwik\Tracker\Request; use Piwik\Tracker\Visitor; use Piwik\Translate; use Piwik\Plugin\Segment; +use Piwik\Plugin; +use Exception; /** + * Defines a new conversion dimension that records any visit related information during tracking. + * + * You can record any visit information by implementing one of the following events: + * {@link onEcommerceOrderConversion()}, {@link onEcommerceCartUpdateConversion()} or {@link onGoalConversion()}. + * By defining a {@link $columnName} and {@link $columnType} a new column will be created in the database + * (table `log_conversion`) 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 */ @@ -28,6 +40,36 @@ abstract class ConversionDimension extends Dimension { private $tableName = 'log_conversion'; + /** + * Installs the conversion dimension in case it is not installed yet. The installation is already implemented based + * on the {@link $columnName} and {@link $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_conversion` MySQL table. + * + * Example: + * ``` + public function install() + { + $changes = parent::install(); + $changes['log_conversion'][] = "ADD INDEX index_idsite_servertime ( idsite, server_time )"; + + return $changes; + } + ``` + * + * @return 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_conversion' => array("ADD COLUMN `$this->columnName` $this->columnType", "ADD INDEX ...") + ); + ``` + * @api + */ public function install() { if (empty($this->columnName) || empty($this->columnType)) { @@ -39,6 +81,11 @@ abstract class ConversionDimension extends Dimension ); } + /** + * @see ActionDimension::update() + * @return array + * @ignore + */ public function update() { if (empty($this->columnName) || empty($this->columnType)) { @@ -50,6 +97,14 @@ abstract class ConversionDimension extends Dimension ); } + /** + * 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)) { @@ -59,18 +114,31 @@ abstract class ConversionDimension extends Dimension try { $sql = "ALTER TABLE `" . Common::prefixTable($this->tableName) . "` DROP COLUMN `$this->columnName`"; Db::exec($sql); - } catch (\Exception $e) { + } catch (Exception $e) { if (!Db::get()->isErrNo($e, '1091')) { throw $e; } } } + /** + * @see ActionDimension::getVersion() + * @return string + * @ignore + */ public function getVersion() { return $this->columnType; } + /** + * Adds a new segment. It automatically sets the SQL segment depending on the column name in case none is set + * already. + * + * @see \Piwik\Columns\Dimension::addSegment() + * @param Segment $segment + * @api + */ protected function addSegment(Segment $segment) { $sqlSegment = $segment->getSqlSegment(); @@ -81,7 +149,10 @@ abstract class ConversionDimension extends Dimension parent::addSegment($segment); } - /** @return \Piwik\Plugin\Dimension\ConversionDimension[] */ + /** + * Get all conversion dimensions that are defined by all activated plugins. + * @ignore + */ public static function getAllDimensions() { $cache = new PluginAwareStaticCache('ConversionDimensions'); @@ -103,8 +174,13 @@ abstract class ConversionDimension extends Dimension return $cache->get(); } - /** @return \Piwik\Plugin\Dimension\ConversionDimension[] */ - public static function getDimensions(\Piwik\Plugin $plugin) + /** + * Get all conversion dimensions that are defined by the given plugin. + * @param Plugin $plugin + * @return ConversionDimension[] + * @ignore + */ + public static function getDimensions(Plugin $plugin) { $dimensions = $plugin->findMultipleComponents('Columns', '\\Piwik\\Plugin\\Dimension\\ConversionDimension'); $instances = array(); @@ -117,12 +193,16 @@ abstract class ConversionDimension extends Dimension } /** + * This event is triggered when an ecommerce order is converted. Any returned value will be persist in the database. + * Return boolean `false` if you do not want to change the value in some cases. + * * @param Request $request * @param Visitor $visitor * @param Action|null $action * @param GoalManager $goalManager * * @return mixed|false + * @api */ public function onEcommerceOrderConversion(Request $request, Visitor $visitor, $action, GoalManager $goalManager) { @@ -130,12 +210,16 @@ abstract class ConversionDimension extends Dimension } /** + * This event is triggered when an ecommerce cart update is converted. Any returned value will be persist in the + * database. Return boolean `false` if you do not want to change the value in some cases. + * * @param Request $request * @param Visitor $visitor * @param Action|null $action * @param GoalManager $goalManager * * @return mixed|false + * @api */ public function onEcommerceCartUpdateConversion(Request $request, Visitor $visitor, $action, GoalManager $goalManager) { @@ -143,12 +227,16 @@ abstract class ConversionDimension extends Dimension } /** + * This event is triggered when an any custom goal is converted. Any returned value will be persist in the + * database. Return boolean `false` if you do not want to change the value in some cases. + * * @param Request $request * @param Visitor $visitor * @param Action|null $action * @param GoalManager $goalManager * * @return mixed|false + * @api */ public function onGoalConversion(Request $request, Visitor $visitor, $action, GoalManager $goalManager) { diff --git a/core/Plugin/Dimension/VisitDimension.php b/core/Plugin/Dimension/VisitDimension.php index cf7204bdd5..594791f920 100644 --- a/core/Plugin/Dimension/VisitDimension.php +++ b/core/Plugin/Dimension/VisitDimension.php @@ -19,8 +19,19 @@ use Piwik\Tracker\Visitor; use Piwik\Tracker\Action; use Piwik\Tracker; use Piwik\Translate; +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 */ @@ -28,6 +39,36 @@ abstract class VisitDimension extends Dimension { private $tableName = 'log_visit'; + /** + * Installs the visit dimension in case it is not installed yet. The installation is already implemented based on + * the {@link $columnName} and {@link $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_visit` MySQL table. + * + * Example: + * ``` + public function install() + { + $changes = parent::install(); + $changes['log_visit'][] = "ADD INDEX index_idsite_servertime ( idsite, server_time )"; + + return $changes; + } + ``` + * + * @return 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_visit' => array("ADD COLUMN `$this->columnName` $this->columnType", "ADD INDEX ...") + ); + ``` + * @api + */ public function install() { if (!$this->columnType) { @@ -45,6 +86,12 @@ abstract class VisitDimension extends Dimension return $changes; } + /** + * @see ActionDimension::update() + * @param array $conversionColumns An array of currently installed columns in the conversion table. + * @return array + * @ignore + */ public function update($conversionColumns) { if (!$this->columnType) { @@ -69,6 +116,11 @@ abstract class VisitDimension extends Dimension return $changes; } + /** + * @see ActionDimension::getVersion() + * @return string + * @ignore + */ public function getVersion() { return $this->columnType . $this->isHandlingLogConversion(); @@ -83,6 +135,14 @@ abstract class VisitDimension extends Dimension 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)) { @@ -92,7 +152,7 @@ abstract class VisitDimension extends Dimension try { $sql = "ALTER TABLE `" . Common::prefixTable($this->tableName) . "` DROP COLUMN `$this->columnName`"; Db::exec($sql); - } catch (\Exception $e) { + } catch (Exception $e) { if (!Db::get()->isErrNo($e, '1091')) { throw $e; } @@ -101,13 +161,20 @@ abstract class VisitDimension extends Dimension try { $sql = "ALTER TABLE `" . Common::prefixTable('log_conversion') . "` DROP COLUMN `$this->columnName`"; Db::exec($sql); - } catch (\Exception $e) { + } catch (Exception $e) { if (!Db::get()->isErrNo($e, '1091')) { throw $e; } } } + /** + * Adds a new segment. It automatically sets the SQL segment depending on the column name in case none is set + * already. + * @see \Piwik\Columns\Dimension::addSegment() + * @param Segment $segment + * @api + */ protected function addSegment(Segment $segment) { $sqlSegment = $segment->getSqlSegment(); @@ -118,38 +185,90 @@ abstract class VisitDimension extends Dimension parent::addSegment($segment); } + /** + * 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 Request $request * @param Visitor $visitor * @param Action|null $action - * @return mixed + * @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 implemting this event. By returning boolean + * `false` no value will be updated. + * + * @param Request $request + * @param Visitor $visitor + * @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 Request $request + * @param Visitor $visitor + * @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 Request $request + * @param Visitor $visitor + * @param Action|null $action + * @return mixed|false + * @api + */ public function onAnyGoalConversion(Request $request, Visitor $visitor, $action) { return false; } - /** @return \Piwik\Plugin\Dimension\VisitDimension[] */ + /** + * Get all visit dimensions that are defined by all activated plugins. + * @return VisitDimension[] + */ public static function getAllDimensions() { $cache = new PluginAwareStaticCache('VisitDimensions'); @@ -173,6 +292,9 @@ abstract class VisitDimension extends Dimension return $cache->get(); } + /** + * @ignore + */ public static function sortByRequiredFields($a, $b) { $fields = $a->getRequiredVisitFields(); @@ -188,8 +310,13 @@ abstract class VisitDimension extends Dimension return 0; } - /** @return \Piwik\Plugin\Dimension\VisitDimension[] */ - public static function getDimensions(\Piwik\Plugin $plugin) + /** + * Get all visit dimensions that are defined by the given plugin. + * @param Plugin $plugin + * @return VisitDimension[] + * @ignore + */ + public static function getDimensions(Plugin $plugin) { $dimensions = $plugin->findMultipleComponents('Columns', '\\Piwik\\Plugin\\Dimension\\VisitDimension'); $instances = array(); |