Refs #7276, fill out UpdateListener, use UpdateListener in core/Updater update process and document UpdateListener.

1 files changed, 100 insertions, 4 deletions

diff --git a/core/Updater/UpdateListener.php b/core/Updater/UpdateListener.php
index 3d8afb8ac3..deb3d458b2 100644
--- a/core/Updater/UpdateListener.php
+++ b/core/Updater/UpdateListener.php
@@ -8,11 +8,107 @@
 namespace Piwik\Updater;
 
 /**
- * TODO
- *
- * TODO: rename UpdaterListener?
+ * UpdateListeners can be used to inject logic into the component updating process. Derive
+ * from this base class and add an instance of the derived class to a Updater instance. When
+ * Updater::update() is called, the methods in the added UpdateListeners will be executed
+ * accordingly.
  */
-interface UpdateListener
+abstract class UpdateListener
 {
+    /**
+     * Executed when a component is about to be updated. At this point, no SQL queries or other
+     * updating logic has been executed.
+     *
+     * @param string $name The name of the component being updated.
+     */
+    public function onComponentUpdateStarting($name)
+    {
+        // empty
+    }
+
+    /**
+     * Executed after a component has been successfully updated.
+     *
+     * @param string $name The name of the component being updated.
+     * @param string $version The version of the component that was updated.
+     * @param string[] $warnings Any warnings that occurred during the component update process.
+     */
+    public function onComponentUpdateFinished($name, $version, $warnings)
+    {
+        // empty
+    }
+
+    /**
+     * Executed before the update method of an Updates class is executed.
+     *
+     * @param string $componentName The name of the component being updated.
+     * @param string $file The path to the Updates file being executed.
+     * @param string $updateClassName The name of the Update class that should exist within the Update file.
+     * @param string $version The version the Updates file belongs to.
+     */
+    public function onComponentUpdateFileStarting($componentName, $file, $updateClassName, $version)
+    {
+        // empty
+    }
+
+    /**
+     * Executed after the update method of an Updates class is successfully executed.
+     *
+     * @param string $componentName The name of the component being updated.
+     * @param string $file The path to the Updates file being executed.
+     * @param string $updateClassName The name of the Update class that should exist within the Update file.
+     * @param string $version The version the Updates file belongs to.
+     */
+    public function onComponentUpdateFileFinished($componentName, $file, $updateClassName, $version)
+    {
+        // empty
+    }
+
+    /**
+     * Executed before a migration query is executed.
+     *
+     * @param string $updateFile The path to the Updates file being executed.
+     * @param string $sql The SQL query that is about to be executed.
+     */
+    public function onStartExecutingMigrationQuery($updateFile, $sql)
+    {
+        // empty
+    }
+
+    /**
+     * Executed after a migration query is executed.
+     *
+     * @param string $updateFile The path to the Updates file being executed.
+     * @param string $sql The SQL query that has finished executing.
+     */
+    public function onFinishedExecutingMigrationQuery($updateFile, $sql)
+    {
+        // empty
+    }
+
+    /**
+     * Executed when a warning occurs during the update process. A warning occurs when an Updates file
+     * throws an exception that is not a UpdaterErrorException.
+     *
+     * @param string $componentName The name of the component being updated.
+     * @param string $version The version of the Updates file during which the warning occurred.
+     * @param \Exception $exception The exception that generated the warning.
+     */
+    public function onWarning($componentName, $version, \Exception $exception)
+    {
+        // empty
+    }
 
+    /**
+     * Executed when an error occurs during the update process. An error occurs when an Updates file
+     * throws a UpdaterErrorException.
+     *
+     * @param string $componentName The name of the component being updated.
+     * @param string $version The version of the Updates file during which the error occurred.
+     * @param \Exception $exception The exception that generated the error.
+     */
+    public function onError($componentName, $version, \Exception $exception)
+    {
+        // empty
+    }
 }
\ No newline at end of file