[5.0][RFC][Events] Make captcha plugins use plugin events

libraries/src/Captcha/Captcha.php

@@ -37,9 +37,19 @@ class Captcha implements DispatcherAwareInterface
      *
      * @var    CMSPlugin
      * @since  2.5
+     *
+     * @deprecated  Should use Provider instance
      */
     private $captcha;
 
+    /**
+     * Captcha Provider instance
+     *
+     * @var    CaptchaProviderInterface
+     * @since  __DEPLOY_VERSION__
+     */
+    private $provider;
+
     /**
      * Editor Plugin name
      *
@@ -69,13 +79,25 @@ public function __construct($captcha, $options)
     {
         $this->name = $captcha;
 
-        if (!empty($options['dispatcher']) && $options['dispatcher'] instanceof DispatcherInterface) {
-            $this->setDispatcher($options['dispatcher']);
+        /** @var  CaptchaRegistry  $registry */
+        $registry = $options['registry'] ?? Factory::getContainer()->get(CaptchaRegistry::class);
+
+        if ($registry->has($captcha)) {
+            $this->provider = $registry->get($captcha);
         } else {
-            $this->setDispatcher(Factory::getApplication()->getDispatcher());
+            @trigger_error(
+                'Use of legacy Captcha is deprecated. Use onCaptchaSetup event to register your Captcha provider.',
+                E_USER_DEPRECATED
+            );
+
+            if (!empty($options['dispatcher']) && $options['dispatcher'] instanceof DispatcherInterface) {
+                $this->setDispatcher($options['dispatcher']);
+            } else {
+                $this->setDispatcher(Factory::getApplication()->getDispatcher());
+            }
+
+            $this->_load($options);
         }
-
-        $this->_load($options);
     }
 
     /**
@@ -110,9 +132,15 @@ public static function getInstance($captcha, array $options = [])
      *
      * @since   2.5
      * @throws  \RuntimeException
+     *
+     * @deprecated  Without replacement
      */
     public function initialise($id)
     {
+        if ($this->provider) {
+            return true;
+        }
+
         $arg = ['id' => $id];
 
         $this->update('onInit', $arg);
@@ -134,6 +162,13 @@ public function initialise($id)
      */
     public function display($name, $id, $class = '')
     {
+        if ($this->provider) {
+            return $this->provider->display($name, [
+                'id'    => $id ?: $name,
+                'class' => $class,
+            ]);
+        }
+
         // Check if captcha is already loaded.
         if ($this->captcha === null) {
             return '';
@@ -167,6 +202,10 @@ public function display($name, $id, $class = '')
      */
     public function checkAnswer($code)
     {
+        if ($this->provider) {
+            return $this->provider->checkAnswer($code);
+        }
+
         // Check if captcha is already loaded
         if ($this->captcha === null) {
             return false;
@@ -190,6 +229,11 @@ public function checkAnswer($code)
      */
     public function setupField(CaptchaField $field, \SimpleXMLElement $element)
     {
+        if ($this->provider) {
+            $this->provider->setupField($field, $element);
+            return;
+        }
+
         if ($this->captcha === null) {
             return;
         }
@@ -208,6 +252,8 @@ public function setupField(CaptchaField $field, \SimpleXMLElement $element)
      * @return  mixed
      *
      * @since   4.0.0
+     *
+     * @deprecated  Without replacement
      */
     private function update($name, &$args)
     {
@@ -227,6 +273,8 @@ private function update($name, &$args)
      *
      * @since   2.5
      * @throws  \RuntimeException
+     *
+     * @deprecated  Should use CaptchaRegistry
      */
     private function _load(array $options = [])
     {

libraries/src/Captcha/CaptchaProviderInterface.php

@@ -0,0 +1,70 @@
+<?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\Captcha;
+
+use Joomla\CMS\Form\FormField;
+
+/**
+ * Captcha Provider Interface
+ *
+ * @since   __DEPLOY_VERSION__
+ */
+interface CaptchaProviderInterface
+{
+    /**
+     * Return Captcha name, CMD string.
+     *
+     * @return string
+     * @since   __DEPLOY_VERSION__
+     */
+    public function getName(): string;
+
+    /**
+     * Gets the challenge HTML
+     *
+     * @param   string  $name        Input name
+     * @param   array   $attributes  The class of the field
+     *
+     * @return  string  The HTML to be embedded in the form
+     *
+     * @since   __DEPLOY_VERSION__
+     *
+     * @throws  \RuntimeException
+     */
+    public function display(string $name = '', array $attributes = []): string;
+
+    /**
+     * Calls an HTTP POST function to verify if the user's guess was correct.
+     *
+     * @param   string  $code  Answer provided by user
+     *
+     * @return  bool    If the answer is correct, false otherwise
+     *
+     * @since   __DEPLOY_VERSION__
+     *
+     * @throws  \RuntimeException
+     */
+    public function checkAnswer(string $code = null): bool;
+
+    /**
+     * Method to react on the setup of a captcha field. Gives the possibility
+     * to change the field and/or the XML element for the field.
+     *
+     * @param   FormField          $field    Captcha field instance
+     * @param   \SimpleXMLElement  $element  XML form definition
+     *
+     * @return void
+     *
+     * @since  __DEPLOY_VERSION__
+     *
+     * @throws  \RuntimeException
+     */
+    public function setupField(FormField $field, \SimpleXMLElement $element): void;
+}

libraries/src/Captcha/CaptchaRegistry.php

@@ -0,0 +1,119 @@
+<?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\Captcha;
+
+use Joomla\CMS\Captcha\Exception\CaptchaNotFoundException;
+use Joomla\CMS\Event\Captcha\CaptchaSetupEvent;
+use Joomla\Event\DispatcherAwareInterface;
+use Joomla\Event\DispatcherAwareTrait;
+
+// phpcs:disable PSR1.Files.SideEffects
+\defined('JPATH_PLATFORM') or die;
+// phpcs:enable PSR1.Files.SideEffects
+
+/**
+ * Captcha Registry class
+ * @since   __DEPLOY_VERSION__
+ */
+final class CaptchaRegistry implements DispatcherAwareInterface
+{
+    use DispatcherAwareTrait;
+
+    /**
+     * List of registered elements
+     *
+     * @var    CaptchaProviderInterface[]
+     * @since   __DEPLOY_VERSION__
+     */
+    private $registry = [];
+
+    /**
+     * Internal flag of initialisation
+     *
+     * @var    boolean
+     * @since   __DEPLOY_VERSION__
+     */
+    private $initialised = false;
+
+    /**
+     * Return list of all registered elements
+     *
+     * @return CaptchaProviderInterface[]
+     * @since    __DEPLOY_VERSION__
+     */
+    public function getAll(): array
+    {
+        return array_values($this->registry);
+    }
+
+    /**
+     * Check whether the element exists in the registry.
+     *
+     * @param   string  $name  Element name
+     *
+     * @return  bool
+     * @since    __DEPLOY_VERSION__
+     */
+    public function has(string $name): bool
+    {
+        return !empty($this->registry[$name]);
+    }
+
+    /**
+     * Return element by name.
+     *
+     * @param   string  $name  Element name
+     *
+     * @return  CaptchaProviderInterface
+     * @throws  CaptchaNotFoundException
+     * @since    __DEPLOY_VERSION__
+     */
+    public function get(string $name): CaptchaProviderInterface
+    {
+        if (empty($this->registry[$name])) {
+            throw new CaptchaNotFoundException(sprintf('Captcha element "%s" not found in the registry.', $name));
+        }
+
+        return $this->registry[$name];
+    }
+
+    /**
+     * Register element in registry, add new or override existing.
+     *
+     * @param   CaptchaProviderInterface $instance
+     *
+     * @return  static
+     * @since    __DEPLOY_VERSION__
+     */
+    public function add(CaptchaProviderInterface $instance)
+    {
+        $this->registry[$instance->getName()] = $instance;
+
+        return $this;
+    }
+
+    /**
+     * Trigger event to allow register the element through plugins.
+     *
+     * @return  static
+     * @since   __DEPLOY_VERSION__
+     */
+    public function initRegistry()
+    {
+        if (!$this->initialised) {
+            $this->initialised = true;
+
+            $event = new CaptchaSetupEvent('onCaptchaSetup', ['subject' => $this]);
+            $this->getDispatcher()->dispatch($event->getName(), $event);
+        }
+
+        return $this;
+    }
+}

libraries/src/Captcha/Exception/CaptchaNotFoundException.php

@@ -0,0 +1,23 @@
+<?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\Captcha\Exception;
+
+// phpcs:disable PSR1.Files.SideEffects
+\defined('JPATH_PLATFORM') or die;
+// phpcs:enable PSR1.Files.SideEffects
+
+/**
+ * Exception class defining a missing element
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+class CaptchaNotFoundException extends \RuntimeException
+{
+}