[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
   8   */
   9  
  10  namespace Joomla\CMS\Event;
  11  
  12  use BadMethodCallException;
  13  use Joomla\Event\Event;
  14  use Joomla\Event\Event as BaseEvent;
  15  use Joomla\String\Normalise;
  16  
  17  // phpcs:disable PSR1.Files.SideEffects
  18  \defined('JPATH_PLATFORM') or die;
  19  // phpcs:enable PSR1.Files.SideEffects
  20  
  21  /**
  22   * This class implements the base Event object used system-wide to offer orthogonality. Core objects such as Models,
  23   * Controllers, etc create such events on-the-fly and dispatch them through the application's Dispatcher (colloquially
  24   * known as the "Joomla! plugin system"). This way a suitable plugin, typically a "system" plugin, can modify the
  25   * behaviour of any internal class, providing system-wide services such as tags, content versioning, comments or even
  26   * low-level services such as the implementation of created/modified/locked behaviours, record hit counter etc.
  27   *
  28   * You can create a new Event with something like this:
  29   *
  30   * $event = AbstractEvent::create('onModelBeforeSomething', $myModel, $arguments);
  31   *
  32   * You can access the subject object from your event Listener using $event['subject']. It is up to your listener to
  33   * determine whether it should apply its functionality against the subject.
  34   *
  35   * This AbstractEvent class implements a mutable event which is allowed to change its arguments at runtime. This is
  36   * generally unadvisable. It's best to use AbstractImmutableEvent instead and constrict all your interaction to the
  37   * subject class.
  38   *
  39   * @since  4.0.0
  40   */
  41  abstract class AbstractEvent extends BaseEvent
  42  {
  43      use CoreEventAware;
  44  
  45      /**
  46       * Creates a new CMS event object for a given event name and subject. The following arguments must be given:
  47       * subject      object  The subject of the event. This is the core object you are going to manipulate.
  48       * eventClass   string  The Event class name. If you do not provide it Joomla\CMS\Events\<eventNameWithoutOnPrefix>
  49       *                      will be used.
  50       *
  51       * @param   string  $eventName  The name of the event, e.g. onTableBeforeLoad
  52       * @param   array   $arguments  Additional arguments to pass to the event
  53       *
  54       * @return  static
  55       *
  56       * @since   4.0.0
  57       * @throws  BadMethodCallException  If you do not provide a subject argument
  58       */
  59      public static function create(string $eventName, array $arguments = [])
  60      {
  61          // Get the class name from the arguments, if specified
  62          $eventClassName = '';
  63  
  64          if (isset($arguments['eventClass'])) {
  65              $eventClassName = $arguments['eventClass'];
  66  
  67              unset($arguments['eventClass']);
  68          }
  69  
  70          /**
  71           * If the class name isn't set/found determine it from the event name, e.g. TableBeforeLoadEvent from
  72           * the onTableBeforeLoad event name.
  73           */
  74          if (empty($eventClassName) || !class_exists($eventClassName, true)) {
  75              $bareName = strpos($eventName, 'on') === 0 ? substr($eventName, 2) : $eventName;
  76              $parts = Normalise::fromCamelCase($bareName, true);
  77              $eventClassName = __NAMESPACE__ . '\\' . ucfirst(array_shift($parts)) . '\\';
  78              $eventClassName .= implode('', $parts);
  79              $eventClassName .= 'Event';
  80          }
  81  
  82          // Make sure a non-empty subject argument exists and that it is an object
  83          if (!isset($arguments['subject']) || empty($arguments['subject']) || !\is_object($arguments['subject'])) {
  84              throw new BadMethodCallException("No subject given for the $eventName event");
  85          }
  86  
  87          // Create and return the event object
  88          if (class_exists($eventClassName, true)) {
  89              return new $eventClassName($eventName, $arguments);
  90          }
  91  
  92          /**
  93           * The detection code above failed. This is to be expected, it was written back when we only
  94           * had the Table events. It does not address most other core events. So, let's use our
  95           * fancier detection instead.
  96           */
  97          $eventClassName = self::getEventClassByEventName($eventName);
  98  
  99          if (!empty($eventClassName) && ($eventClassName !== Event::class)) {
 100              return new $eventClassName($eventName, $arguments);
 101          }
 102  
 103          return new GenericEvent($eventName, $arguments);
 104      }
 105  
 106      /**
 107       * Constructor. Overridden to go through the argument setters.
 108       *
 109       * @param   string  $name       The event name.
 110       * @param   array   $arguments  The event arguments.
 111       *
 112       * @since   4.0.0
 113       */
 114      public function __construct(string $name, array $arguments = [])
 115      {
 116          parent::__construct($name, $arguments);
 117  
 118          $this->arguments = [];
 119  
 120          foreach ($arguments as $argumentName => $value) {
 121              $this->setArgument($argumentName, $value);
 122          }
 123      }
 124  
 125      /**
 126       * Get an event argument value. It will use a getter method if one exists. The getters have the signature:
 127       *
 128       * get<ArgumentName>($value): mixed
 129       *
 130       * where:
 131       *
 132       * $value  is the value currently stored in the $arguments array of the event
 133       * It returns the value to return to the caller.
 134       *
 135       * @param   string  $name     The argument name.
 136       * @param   mixed   $default  The default value if not found.
 137       *
 138       * @return  mixed  The argument value or the default value.
 139       *
 140       * @since   4.0.0
 141       */
 142      public function getArgument($name, $default = null)
 143      {
 144          $methodName = 'get' . ucfirst($name);
 145  
 146          $value = parent::getArgument($name, $default);
 147  
 148          if (method_exists($this, $methodName)) {
 149              return $this->{$methodName}($value);
 150          }
 151  
 152          return $value;
 153      }
 154  
 155      /**
 156       * Add argument to event. It will use a setter method if one exists. The setters have the signature:
 157       *
 158       * set<ArgumentName>($value): mixed
 159       *
 160       * where:
 161       *
 162       * $value  is the value being set by the user
 163       * It returns the value to return to set in the $arguments array of the event.
 164       *
 165       * @param   string  $name   Argument name.
 166       * @param   mixed   $value  Value.
 167       *
 168       * @return  $this
 169       *
 170       * @since   4.0.0
 171       */
 172      public function setArgument($name, $value)
 173      {
 174          $methodName = 'set' . ucfirst($name);
 175  
 176          if (method_exists($this, $methodName)) {
 177              $value = $this->{$methodName}($value);
 178          }
 179  
 180          return parent::setArgument($name, $value);
 181      }
 182  }