[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Joomla! Content Management System
   5   *
   6   * @copyright  (C) 2016 Open Source Matters, Inc. <https://www.joomla.org>
   7   * @license    GNU General Public License version 2 or later; see LICENSE.txt
   8   */
   9  
  10  namespace Joomla\CMS\Helper;
  11  
  12  use Exception;
  13  use Joomla\CMS\Application\CMSApplication;
  14  use Joomla\CMS\Factory;
  15  use Joomla\CMS\HTML\HTMLHelper;
  16  use Joomla\CMS\Language\Text;
  17  use Joomla\CMS\Plugin\PluginHelper;
  18  
  19  // phpcs:disable PSR1.Files.SideEffects
  20  \defined('JPATH_PLATFORM') or die;
  21  // phpcs:enable PSR1.Files.SideEffects
  22  
  23  /**
  24   * Authentication helper class
  25   *
  26   * @since  3.6.3
  27   */
  28  abstract class AuthenticationHelper
  29  {
  30      /**
  31       * No longer used
  32       *
  33       * @return  array  Always empty
  34       *
  35       * @since   3.6.3
  36       * @deprecated 4.2.0 Will be removed in 5.0.
  37       */
  38      public static function getTwoFactorMethods()
  39      {
  40          return [];
  41      }
  42  
  43      /**
  44       * Get additional login buttons to add in a login module. These buttons can be used for
  45       * authentication methods external to Joomla such as WebAuthn, login with social media
  46       * providers, login with third party providers or even login with third party Single Sign On
  47       * (SSO) services.
  48       *
  49       * Button definitions are returned by the onUserLoginButtons event handlers in plugins. By
  50       * default, only system and user plugins are taken into account. The former because they are
  51       * always loaded. The latter are explicitly loaded in this method.
  52       *
  53       * The onUserLoginButtons event handlers must conform to the following method definition:
  54       *
  55       * public function onUserLoginButtons(string $formId): array
  56       *
  57       * The onUserLoginButtons event handlers must return a simple array containing 0 or more button
  58       * definitions.
  59       *
  60       * Each button definition is a hash array with the following keys:
  61       *
  62       * * `label`   The translation string used as the label and title of the button. Required
  63       * * `id`      The HTML ID of the button. Required.
  64       * * `tooltip` (optional) The translation string used as the alt tag of the button's image
  65       * * `onclick` (optional) The onclick attribute, used to fire a JavaScript event. Not
  66       *             recommended.
  67       * * `data-*`  (optional) Data attributes to pass verbatim. Use these and JavaScript to handle
  68       *             the button.
  69       * * `icon`    (optional) A CSS class for an optional icon displayed before the label; has
  70       *             precedence over 'image'
  71       * * `image`   (optional) An image path for an optional icon displayed before the label
  72       * * `class`   (optional) CSS class(es) to be added to the button
  73       *
  74       * You can find a real world implementation of the onUserLoginButtons plugin event in the
  75       * system/webauthn plugin.
  76       *
  77       * You can find a real world implementation of consuming the output of this method in the
  78       * modules/mod_login module.
  79       *
  80       * Third party developers implementing a login module or a login form in their component are
  81       * strongly advised to call this method and consume its results to display additional login
  82       * buttons. Not doing that means that you are not fully compatible with Joomla 4.
  83       *
  84       * @param   string  $formId  The HTML ID of the login form container. Use it to filter when and
  85       *                           where to show your additional login button(s)
  86       *
  87       * @return  array  Button definitions.
  88       *
  89       * @since   4.0.0
  90       */
  91      public static function getLoginButtons(string $formId): array
  92      {
  93          // Get all the User plugins.
  94          PluginHelper::importPlugin('user');
  95  
  96          // Trigger the onUserLoginButtons event and return the button definitions.
  97          try {
  98              /** @var CMSApplication $app */
  99              $app = Factory::getApplication();
 100          } catch (Exception $e) {
 101              return [];
 102          }
 103  
 104          $results        = $app->triggerEvent('onUserLoginButtons', [$formId]);
 105          $buttons        = [];
 106  
 107          foreach ($results as $result) {
 108              // Did we get garbage back from the plugin?
 109              if (!is_array($result) || empty($result)) {
 110                  continue;
 111              }
 112  
 113              // Did the developer accidentally return a single button definition instead of an array?
 114              if (array_key_exists('label', $result)) {
 115                  $result = [$result];
 116              }
 117  
 118              // Process each button, making sure it conforms to the required definition
 119              foreach ($result as $item) {
 120                  // Force mandatory fields
 121                  $defaultButtonDefinition = [
 122                      'label'   => '',
 123                      'tooltip' => '',
 124                      'icon'    => '',
 125                      'image'   => '',
 126                      'class'   => '',
 127                      'id'      => '',
 128                      'onclick' => '',
 129                  ];
 130  
 131                  $button = array_merge($defaultButtonDefinition, $item);
 132  
 133                  // Unset anything that doesn't conform to a button definition
 134                  foreach (array_keys($button) as $key) {
 135                      if (substr($key, 0, 5) == 'data-') {
 136                          continue;
 137                      }
 138  
 139                      if (!in_array($key, ['label', 'tooltip', 'icon', 'image', 'svg', 'class', 'id', 'onclick'])) {
 140                          unset($button[$key]);
 141                      }
 142                  }
 143  
 144                  // We need a label and an ID as the bare minimum
 145                  if (empty($button['label']) || empty($button['id'])) {
 146                      continue;
 147                  }
 148  
 149                  $buttons[] = $button;
 150              }
 151          }
 152  
 153          return $buttons;
 154      }
 155  }