refs #5820 added documentation and improved code

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