[5.4] Implement autoupdate plugin events (#45696)

This PR adds a new plugin event that allows 3rd party extensions to stop automatted updates. This allows 3rd party developers to i.e. enforce special conditions like "only perform auto updates if a backup using my backup extension has been performed in the last 24h".

Furthermore, this PR also fixed the version number in the "failed update" notfication that is sent when an update is blocked by a plugin.

Side note: A new "after update" event is not required, as the default after update event will be called.

Author: SniperSister

administrator/components/com_joomlaupdate/src/Model/NotificationModel.php

@@ -39,12 +39,13 @@ final class NotificationModel extends BaseDatabaseModel
      *
      * @param  string  $type        The type of notification to send. This is the last key for the mail template
      * @param  string  $oldVersion  The old version from before the update
+     * @param  string  $newVersion  The new version from after the update
      *
      * @return  void
      *
      * @since   5.4.0
      */
-    public function sendNotification($type, $oldVersion): void
+    public function sendNotification($type, $oldVersion, $newVersion): void
     {
         $params = ComponentHelper::getParams('com_joomlaupdate');
 
@@ -58,7 +59,6 @@ public function sendNotification($type, $oldVersion): void
         $app        = Factory::getApplication();
         $jLanguage  = $app->getLanguage();
         $sitename   = $app->get('sitename');
-        $newVersion = (new Version())->getShortVersion();
 
         $substitutions = [
             'oldversion' => $oldVersion,

administrator/components/com_joomlaupdate/src/Model/UpdateModel.php

@@ -13,6 +13,7 @@
 use Joomla\CMS\Authentication\Authentication;
 use Joomla\CMS\Component\ComponentHelper;
 use Joomla\CMS\Event\Extension\AfterJoomlaUpdateEvent;
+use Joomla\CMS\Event\Extension\BeforeJoomlaAutoupdateEvent;
 use Joomla\CMS\Event\Extension\BeforeJoomlaUpdateEvent;
 use Joomla\CMS\Extension\ExtensionHelper;
 use Joomla\CMS\Factory;
@@ -22,6 +23,7 @@
 use Joomla\CMS\Installer\Installer;
 use Joomla\CMS\Language\Text;
 use Joomla\CMS\Log\Log;
+use Joomla\CMS\MVC\Controller\Exception\CheckinCheckout;
 use Joomla\CMS\MVC\Factory\MVCFactoryInterface;
 use Joomla\CMS\MVC\Model\BaseDatabaseModel;
 use Joomla\CMS\Plugin\PluginHelper;
@@ -39,6 +41,7 @@
 use Joomla\Filesystem\File;
 use Joomla\Registry\Registry;
 use Joomla\Utilities\ArrayHelper;
+use Tobscure\JsonApi\Exception\InvalidParameterException;
 
 // phpcs:disable PSR1.Files.SideEffects
 \defined('_JEXEC') or die;
@@ -532,21 +535,37 @@ public function prepareAutoUpdate(string $targetVersion): array
         $fileInformation = $this->download();
 
         if ($fileInformation['version'] !== $targetVersion) {
-            throw new \Exception(Text::_('COM_JOOMLAUPDATE_VIEW_UPDATE_VERSION_WRONG'), 410);
+            throw new InvalidParameterException(Text::_('COM_JOOMLAUPDATE_VIEW_UPDATE_VERSION_WRONG'), 410);
         }
 
         if ($fileInformation['check'] === false) {
-            throw new \Exception(Text::_('COM_JOOMLAUPDATE_VIEW_UPDATE_CHECKSUM_WRONG'), 410);
+            throw new InvalidParameterException(Text::_('COM_JOOMLAUPDATE_VIEW_UPDATE_CHECKSUM_WRONG'), 410);
         }
 
         if (!$this->createUpdateFile($fileInformation['basename'])) {
-            throw new \Exception('Could not write update file', 410);
+            throw new InvalidParameterException(Text::_('COM_JOOMLAUPDATE_VIEW_UPDATE_COULD_NOT_WRITE_UPDATE_FILE'), 410);
         }
 
         Log::add(Text::sprintf('COM_JOOMLAUPDATE_UPDATE_LOG_FILE', $fileInformation['basename']), Log::INFO, 'Update');
 
         $app = Factory::getApplication();
 
+        // Run preparation plugin trigger
+        PluginHelper::importPlugin('installer');
+
+        $eventResult = $this->getDispatcher()->dispatch(
+            'onBeforeJoomlaAutoupdate',
+            new BeforeJoomlaAutoupdateEvent(
+                'onBeforeJoomlaAutoupdate'
+            )
+        );
+
+        if ($eventResult->getArgument('stoppedUpdate')) {
+            Log::add(Text::_('COM_JOOMLAUPDATE_VIEW_UPDATE_STOPPED_BY_PLUGIN'), Log::ERROR, 'Update');
+
+            throw new CheckinCheckout(Text::_('COM_JOOMLAUPDATE_VIEW_UPDATE_STOPPED_BY_PLUGIN'), 503);
+        }
+
         return [
             'password' => $app->getUserState('com_joomlaupdate.password'),
             'filesize' => $app->getUserState('com_joomlaupdate.filesize'),
@@ -824,7 +843,7 @@ public function createUpdateFile($basename = null): bool
         $app      = Factory::getApplication();
 
         // Trigger event before joomla update.
-        $app->getDispatcher()->dispatch('onJoomlaBeforeUpdate', new BeforeJoomlaUpdateEvent('onJoomlaBeforeUpdate'));
+        $this->getDispatcher()->dispatch('onJoomlaBeforeUpdate', new BeforeJoomlaUpdateEvent('onJoomlaBeforeUpdate'));
 
         // Get the absolute path to site's root.
         $siteroot = JPATH_SITE;
@@ -1161,7 +1180,7 @@ public function cleanUp()
         $oldVersion = $app->getUserState('com_joomlaupdate.oldversion');
 
         // Trigger event after joomla update.
-        $app->getDispatcher()->dispatch('onJoomlaAfterUpdate', new AfterJoomlaUpdateEvent('onJoomlaAfterUpdate', [
+        $this->getDispatcher()->dispatch('onJoomlaAfterUpdate', new AfterJoomlaUpdateEvent('onJoomlaAfterUpdate', [
             'oldVersion' => $oldVersion ?: '',
         ]));
         $app->setUserState('com_joomlaupdate.oldversion', null);

administrator/language/en-GB/com_joomlaupdate.ini

@@ -207,13 +207,15 @@ COM_JOOMLAUPDATE_VIEW_DEFAULT_UPLOAD_INTRO="You can use this feature to update J
 COM_JOOMLAUPDATE_VIEW_UPDATE_BYTESEXTRACTED="Bytes extracted"
 COM_JOOMLAUPDATE_VIEW_UPDATE_BYTESREAD="Bytes read"
 COM_JOOMLAUPDATE_VIEW_UPDATE_CHECKSUM_WRONG="File Checksum Failed"
+COM_JOOMLAUPDATE_VIEW_UPDATE_COULD_NOT_WRITE_UPDATE_FILE="Could not write update file."
 COM_JOOMLAUPDATE_VIEW_UPDATE_DOWNLOADFAILED="Download of update package failed."
 COM_JOOMLAUPDATE_VIEW_UPDATE_FILESEXTRACTED="Files extracted"
 COM_JOOMLAUPDATE_VIEW_UPDATE_FINALISE_CONFIRM_AND_CONTINUE="Confirm & Continue"
 COM_JOOMLAUPDATE_VIEW_UPDATE_FINALISE_HEAD="Joomla Update is finishing and cleaning up"
 COM_JOOMLAUPDATE_VIEW_UPDATE_FINALISE_HEAD_DESC="To complete the update Process please confirm your identity by re-entering the login information for your site "%s" below."
 COM_JOOMLAUPDATE_VIEW_UPDATE_ITEMS="items"
 COM_JOOMLAUPDATE_VIEW_UPDATE_PERCENT="Percent complete"
+COM_JOOMLAUPDATE_VIEW_UPDATE_STOPPED_BY_PLUGIN="Update stopped by plugin."
 COM_JOOMLAUPDATE_VIEW_UPDATE_VERSION_WRONG="The version of the update package and the requested version do not match, try to refresh the update information."
 COM_JOOMLAUPDATE_VIEW_UPLOAD_CAPTIVE_INTRO_BODY="Make sure that the update file you have uploaded comes from the official Joomla download page. Afterwards, please confirm that you want to install it by re-entering the login information for your site "%s" below."
 COM_JOOMLAUPDATE_VIEW_UPLOAD_CAPTIVE_INTRO_HEAD="Are you sure you want to install the file you uploaded?"

api/components/com_joomlaupdate/src/Controller/NotificationController.php

@@ -11,6 +11,7 @@
 namespace Joomla\Component\Joomlaupdate\Api\Controller;
 
 use Joomla\CMS\Language\Text;
+use Joomla\Component\Joomlaupdate\Administrator\Model\NotificationModel;
 use Joomla\Component\Joomlaupdate\Api\View\Updates\JsonapiView;
 
 // phpcs:disable PSR1.Files.SideEffects
@@ -50,10 +51,11 @@ public function failed()
         $this->validateUpdateToken();
 
         $fromVersion = $this->input->json->getString('fromVersion', null);
+        $toVersion   = $this->input->json->getString('toVersion', null);
 
         $view = $this->prepareView();
 
-        $view->notification('failed', $fromVersion);
+        $view->notification('failed', $fromVersion, $toVersion);
 
         return $this;
     }
@@ -70,10 +72,11 @@ public function success()
         $this->validateUpdateToken();
 
         $fromVersion = $this->input->json->getString('fromVersion', null);
+        $toVersion   = $this->input->json->getString('toVersion', null);
 
         $view = $this->prepareView();
 
-        $view->notification('success', $fromVersion);
+        $view->notification('success', $fromVersion, $toVersion);
 
         return $this;
     }
@@ -101,7 +104,7 @@ protected function prepareView()
             throw new \RuntimeException($e->getMessage());
         }
 
-        /** @var UpdateModel $model */
+        /** @var NotificationModel $model */
         $model = $this->getModel('Notification', 'Administrator', ['ignore_request' => true, 'state' => $this->modelState]);
 
         if (!$model) {

api/components/com_joomlaupdate/src/View/Notification/JsonapiView.php

@@ -33,7 +33,7 @@ class JsonapiView extends BaseApiView
      *
      * @since   5.4.0
      */
-    public function notification($type, $oldVersion)
+    public function notification($type, $oldVersion, $newVersion)
     {
         /**
          * @var UpdateModel $model
@@ -43,7 +43,7 @@ public function notification($type, $oldVersion)
 
         try {
             // Perform the finalization action
-            $model->sendNotification($type, $oldVersion);
+            $model->sendNotification($type, $oldVersion, $newVersion);
         } catch (\Throwable $e) {
             $success = false;
         }

libraries/src/Event/CoreEventAware.php

@@ -156,6 +156,7 @@ trait CoreEventAware
         'onExtensionAfterSave'       => Model\AfterSaveEvent::class,
         'onExtensionAfterDelete'     => Model\AfterDeleteEvent::class,
         'onExtensionChangeState'     => Model\BeforeChangeStateEvent::class,
+        'onJoomlaBeforeAutoupdate'   => Extension\BeforeJoomlaAutoupdateEvent::class,
         'onJoomlaBeforeUpdate'       => Extension\BeforeJoomlaUpdateEvent::class,
         'onJoomlaAfterUpdate'        => Extension\AfterJoomlaUpdateEvent::class,
         // Installer

libraries/src/Event/Extension/BeforeJoomlaAutoupdateEvent.php

@@ -0,0 +1,52 @@
+<?php
+
+/**
+ * Joomla! Content Management System
+ *
+ * @copyright  (C) 2025 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license    GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\CMS\Event\Extension;
+
+// phpcs:disable PSR1.Files.SideEffects
+\defined('_JEXEC') or die;
+// phpcs:enable PSR1.Files.SideEffects
+
+/**
+ * Class for Joomla Auto Update events
+ *
+ * @since   __DEPLOY_VERSION__
+ */
+class BeforeJoomlaAutoupdateEvent extends AbstractJoomlaUpdateEvent
+{
+    /**
+     * Constructor.
+     *
+     * @param   string  $name       The event name.
+     * @param   array   $arguments  The event arguments.
+     *
+     * @throws  \BadMethodCallException
+     *
+     * @since   __DEPLOY_VERSION__
+     */
+    public function __construct($name, array $arguments = [])
+    {
+        $arguments['stoppedUpdate'] = false;
+
+        parent::__construct($name, $arguments);
+    }
+
+    /**
+     * Set stop parameter to true
+     *
+     * @return  void
+     *
+     * @since   __DEPLOY_VERSION__
+     */
+    public function stopUpdate()
+    {
+        $this->arguments['stoppedUpdate'] = true;
+        $this->stopPropagation();
+    }
+}