[5.0][Events] Module event classes

administrator/components/com_users/src/Model/CaptiveModel.php

@@ -13,6 +13,7 @@
 use Joomla\CMS\Application\CMSApplication;
 use Joomla\CMS\Component\ComponentHelper;
 use Joomla\CMS\Date\Date;
+use Joomla\CMS\Event\Module;
 use Joomla\CMS\Event\MultiFactor\Captive;
 use Joomla\CMS\Factory;
 use Joomla\CMS\Language\Text;
@@ -21,7 +22,6 @@
 use Joomla\Component\Users\Administrator\DataShape\CaptiveRenderOptions;
 use Joomla\Component\Users\Administrator\Helper\Mfa as MfaHelper;
 use Joomla\Component\Users\Administrator\Table\MfaTable;
-use Joomla\Event\Event;
 
 // phpcs:disable PSR1.Files.SideEffects
 \defined('_JEXEC') or die;
@@ -334,24 +334,22 @@ public function getMethodImage(string $name): string
      * the way this event is handled, taking its return into account. For now, we just abuse the mutable event
      * properties - a feature of the event objects we discussed in the Joomla! 4 Working Group back in August 2015.
      *
-     * @param   Event  $event  The Joomla! event object
+     * @param   Module\AfterModuleListEvent  $event  The Joomla! event object
      *
      * @return  void
      * @throws  \Exception
      *
      * @since 4.2.0
      */
-    public function onAfterModuleList(Event $event): void
+    public function onAfterModuleList(Module\AfterModuleListEvent $event): void
     {
-        $modules = $event->getArgument(0);
+        $modules = $event->getModules();
 
         if (empty($modules)) {
             return;
         }
 
         $this->filterModules($modules);
-
-        $event->setArgument(0, $modules);
     }
 
     /**

libraries/src/Document/Renderer/Html/ModulesRenderer.php

@@ -10,9 +10,11 @@
 namespace Joomla\CMS\Document\Renderer\Html;
 
 use Joomla\CMS\Document\DocumentRenderer;
+use Joomla\CMS\Event\Module;
 use Joomla\CMS\Factory;
 use Joomla\CMS\Helper\ModuleHelper;
 use Joomla\CMS\Layout\LayoutHelper;
+use Joomla\CMS\Proxy\ArrayProxy;
 
 // phpcs:disable PSR1.Files.SideEffects
 \defined('_JEXEC') or die;
@@ -57,7 +59,13 @@ public function render($position, $params = [], $content = null)
             $buffer .= $moduleHtml;
         }
 
-        $app->triggerEvent('onAfterRenderModules', [&$buffer, &$params]);
+        // Dispatch onAfterRenderModules event
+        $event = new Module\AfterRenderModulesEvent('onAfterRenderModules', [
+            'subject'    => $buffer,
+            'attributes' => new ArrayProxy($params),
+        ]);
+        $app->getDispatcher()->dispatch('onAfterRenderModules', $event);
+        $buffer = $event->getContent();
 
         return $buffer;
     }

libraries/src/Event/CoreEventAware.php

@@ -118,6 +118,13 @@ trait CoreEventAware
         'onContentChangeState'          => Model\AfterChangeStateEvent::class,
         'onCategoryChangeState'         => Model\AfterCategoryChangeStateEvent::class,
         'onBeforeBatch'                 => Model\BeforeBatchEvent::class,
+        // Modules
+        'onRenderModule'         => Module\BeforeRenderModuleEvent::class,
+        'onAfterRenderModule'    => Module\AfterRenderModuleEvent::class,
+        'onAfterRenderModules'   => Module\AfterRenderModulesEvent::class,
+        'onPrepareModuleList'    => Module\PrepareModuleListEvent::class,
+        'onAfterModuleList'      => Module\AfterModuleListEvent::class,
+        'onAfterCleanModuleList' => Module\AfterCleanModuleListEvent::class,
         // Extension and Installer
         'onExtensionBeforeInstall'   => Extension\BeforeInstallEvent::class,
         'onExtensionAfterInstall'    => Extension\AfterInstallEvent::class,

libraries/src/Event/Module/AfterCleanModuleListEvent.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * Joomla! Content Management System
+ *
+ * @copyright  (C) 2023 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license    GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\CMS\Event\Module;
+
+// phpcs:disable PSR1.Files.SideEffects
+\defined('_JEXEC') or die;
+// phpcs:enable PSR1.Files.SideEffects
+
+/**
+ * Class for Module events.
+ * Example:
+ *  new AfterCleanModuleListEvent('onEventName', ['subject' => $modules]);
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+class AfterCleanModuleListEvent extends ModuleListEvent
+{
+}

libraries/src/Event/Module/AfterModuleListEvent.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * Joomla! Content Management System
+ *
+ * @copyright  (C) 2023 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license    GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\CMS\Event\Module;
+
+// phpcs:disable PSR1.Files.SideEffects
+\defined('_JEXEC') or die;
+// phpcs:enable PSR1.Files.SideEffects
+
+/**
+ * Class for Module events.
+ * Example:
+ *  new AfterModuleListEvent('onEventName', ['subject' => $modules]);
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+class AfterModuleListEvent extends ModuleListEvent
+{
+}

libraries/src/Event/Module/AfterRenderModuleEvent.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * Joomla! Content Management System
+ *
+ * @copyright  (C) 2023 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license    GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\CMS\Event\Module;
+
+// phpcs:disable PSR1.Files.SideEffects
+\defined('_JEXEC') or die;
+// phpcs:enable PSR1.Files.SideEffects
+
+/**
+ * Class for Module events.
+ * Example:
+ *  new AfterRenderModuleEvent('onEventName', ['subject' => $module, 'attributes' => $attrs]);
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+class AfterRenderModuleEvent extends RenderModuleEvent
+{
+}

libraries/src/Event/Module/AfterRenderModulesEvent.php

@@ -0,0 +1,121 @@
+<?php
+
+/**
+ * Joomla! Content Management System
+ *
+ * @copyright  (C) 2023 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license    GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\CMS\Event\Module;
+
+// phpcs:disable PSR1.Files.SideEffects
+\defined('_JEXEC') or die;
+// phpcs:enable PSR1.Files.SideEffects
+
+/**
+ * Class for Module events.
+ * Example:
+ *  new AfterRenderModulesEvent('onEventName', ['subject' => $content, 'attributes' => $attrs]);
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+class AfterRenderModulesEvent extends ModuleEvent
+{
+    /**
+     * The argument names, in order expected by legacy plugins.
+     *
+     * @var array
+     *
+     * @since  __DEPLOY_VERSION__
+     * @deprecated 5.0 will be removed in 6.0
+     */
+    protected $legacyArgumentsOrder = ['subject', 'attributes'];
+
+    /**
+     * Constructor.
+     *
+     * @param   string  $name       The event name.
+     * @param   array   $arguments  The event arguments.
+     *
+     * @throws  \BadMethodCallException
+     *
+     * @since   __DEPLOY_VERSION__
+     */
+    public function __construct($name, array $arguments = [])
+    {
+        parent::__construct($name, $arguments);
+
+        if (!\array_key_exists('attributes', $this->arguments)) {
+            throw new \BadMethodCallException("Argument 'attributes' of event {$name} is required but has not been provided");
+        }
+    }
+
+    /**
+     * Setter for the subject argument.
+     *
+     * @param   string  $value  The value to set
+     *
+     * @return  object
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    protected function setSubject(string $value): string
+    {
+        return $value;
+    }
+
+    /**
+     * Setter for the attributes argument.
+     *
+     * @param   array|\ArrayAccess  $value  The value to set
+     *
+     * @return  array|\ArrayAccess
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    protected function setAttributes(array|\ArrayAccess $value): array|\ArrayAccess
+    {
+        return $value;
+    }
+
+    /**
+     * Getter for the content.
+     *
+     * @return  object
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    public function getContent(): string
+    {
+        return $this->arguments['subject'];
+    }
+
+    /**
+     * Setter for the content.
+     *
+     * @param   string  $value  The value to set
+     *
+     * @return  self
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    public function setContent(string $value): self
+    {
+        $this->arguments['subject'] = $value;
+
+        return $this;
+    }
+
+    /**
+     * Getter for the attributes argument.
+     *
+     * @return  array|\ArrayAccess
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    public function getAttributes(): array|\ArrayAccess
+    {
+        return $this->arguments['attributes'];
+    }
+}

libraries/src/Event/Module/BeforeRenderModuleEvent.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * Joomla! Content Management System
+ *
+ * @copyright  (C) 2023 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license    GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\CMS\Event\Module;
+
+// phpcs:disable PSR1.Files.SideEffects
+\defined('_JEXEC') or die;
+// phpcs:enable PSR1.Files.SideEffects
+
+/**
+ * Class for Module events.
+ * Example:
+ *  new BeforeRenderModuleEvent('onEventName', ['subject' => $module, 'attributes' => $attrs]);
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+class BeforeRenderModuleEvent extends RenderModuleEvent
+{
+}

libraries/src/Event/Module/ModuleEvent.php

@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * Joomla! Content Management System
+ *
+ * @copyright  (C) 2023 Open Source Matters, Inc. <https://www.joomla.org>
+ * @license    GNU General Public License version 2 or later; see LICENSE.txt
+ */
+
+namespace Joomla\CMS\Event\Module;
+
+use Joomla\CMS\Event\AbstractImmutableEvent;
+use Joomla\CMS\Event\ReshapeArgumentsAware;
+
+// phpcs:disable PSR1.Files.SideEffects
+\defined('_JEXEC') or die;
+// phpcs:enable PSR1.Files.SideEffects
+
+/**
+ * Base class for Module events
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+abstract class ModuleEvent extends AbstractImmutableEvent
+{
+    use ReshapeArgumentsAware;
+
+    /**
+     * The argument names, in order expected by legacy plugins.
+     *
+     * @var array
+     *
+     * @since  __DEPLOY_VERSION__
+     * @deprecated 5.0 will be removed in 6.0
+     */
+    protected $legacyArgumentsOrder = [];
+
+    /**
+     * Constructor.
+     *
+     * @param   string  $name       The event name.
+     * @param   array   $arguments  The event arguments.
+     *
+     * @throws  \BadMethodCallException
+     *
+     * @since   __DEPLOY_VERSION__
+     */
+    public function __construct($name, array $arguments = [])
+    {
+        // Reshape the arguments array to preserve b/c with legacy listeners
+        if ($this->legacyArgumentsOrder) {
+            $arguments = $this->reshapeArguments($arguments, $this->legacyArgumentsOrder);
+        }
+
+        if (!\array_key_exists('subject', $arguments)) {
+            throw new \BadMethodCallException("Argument 'subject' of event {$name} is required but has not been provided");
+        }
+
+        parent::__construct($name, $arguments);
+    }
+}