[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Joomla! Content Management System
   5   *
   6   * @copyright  (C) 2022 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\Result;
  11  
  12  use BadMethodCallException;
  13  use Joomla\Event\Event as BaseEvent;
  14  
  15  // phpcs:disable PSR1.Files.SideEffects
  16  \defined('JPATH_PLATFORM') or die;
  17  // phpcs:enable PSR1.Files.SideEffects
  18  
  19  /**
  20   * This Trait partially implements the ResultAwareInterface for mutable and immutable events.
  21   *
  22   * You must additionally implement the typeCheckResult method or use one of the ResultType*Aware
  23   * traits in your Event handler.
  24   *
  25   * @since  4.2.0
  26   */
  27  trait ResultAware
  28  {
  29      /**
  30       * Disallow setting the result argument directly with setArgument() instead of going through addResult().
  31       *
  32       * You should set this to true ONLY for event names which did NOT exist before Joomla 4.2.0
  33       * or if you are a third party developer introducing new event names for use only in your software.
  34       *
  35       * @var    boolean
  36       * @since  4.2.0
  37       *
  38       * @deprecated 5.0 Using setArgument() for the result argument will always be disallowed.
  39       */
  40      protected $preventSetArgumentResult = false;
  41  
  42      /**
  43       * Appends data to the result array of the event.
  44       *
  45       * @param   mixed  $data  What to add to the result array.
  46       *
  47       * @return  void
  48       * @since   4.2.0
  49       */
  50      public function addResult($data): void
  51      {
  52          // Ensure this trait is applied to an Event object.
  53          if (!($this instanceof BaseEvent)) {
  54              throw new \LogicException(sprintf('Event class ‘%s‘ must implement %s.', get_class($this), BaseEvent::class));
  55          }
  56  
  57          // Ensure the Event object fully implements the ResultAwareInterface.
  58          if (!($this instanceof ResultAwareInterface)) {
  59              throw new \LogicException(sprintf('Event class ‘%s‘ must implement %s.', get_class($this), ResultAwareInterface::class));
  60          }
  61  
  62          // Make sure the data type is correct
  63          $this->typeCheckResult($data);
  64  
  65          // Append the result. We use the arguments property directly to allow this to work on immutable events.
  66          $this->arguments['result']   = $this->arguments['result'] ?? [];
  67          $this->arguments['result'][] = $data;
  68      }
  69  
  70      /**
  71       * Handle setting the result argument directly.
  72       *
  73       * This method serves a dual purpose: backwards compatibility and enforcing the use of addResult.
  74       *
  75       * When $this->preventSetArgumentResult is false it acts as a backwards compatibility shim for
  76       * event handlers expecting generic event classes instead of the concrete Events implemented in
  77       * this package. This allows the migration to concrete event classes throughout the lifetime of
  78       * Joomla 4.x.
  79       *
  80       * When $this->preventSetArgumentResult is false (which will always be the case on Joomla 5.0)
  81       * it will throw a BadMethodCallException if the developer tries to call setArgument('result', ...)
  82       * instead of going through the addResult() method.
  83       *
  84       * @param   array  $value  The new result array.
  85       *
  86       * @return  array
  87       * @since   4.2.0
  88       */
  89      protected function setResult(array $value)
  90      {
  91          if ($this->preventSetArgumentResult) {
  92              throw new BadMethodCallException('You are not allowed to set the result argument directly. Use addResult() instead.');
  93          }
  94  
  95          // Always assume that the last element of the array is the result the handler is trying to append.
  96          $latestValue = array_pop($value);
  97  
  98          $this->addResult($latestValue);
  99  
 100          return $this->arguments['result'];
 101      }
 102  }