[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 InvalidArgumentException;
  13  
  14  // phpcs:disable PSR1.Files.SideEffects
  15  \defined('JPATH_PLATFORM') or die;
  16  // phpcs:enable PSR1.Files.SideEffects
  17  
  18  /**
  19   * This Trait partially implements the ResultAwareInterface for type checking.
  20   *
  21   * Events using this Trait (and the ResultAware trait) will expect event handlers to set results
  22   * of an object type.
  23   *
  24   * If you do not set a list of acceptable result classes any PHP object will satisfy this type check.
  25   *
  26   * @since  4.2.0
  27   */
  28  trait ResultTypeObjectAware
  29  {
  30      /**
  31       * Can the result attribute values also be NULL?
  32       *
  33       * @var    boolean
  34       * @since  4.2.0
  35       */
  36      protected $resultIsNullable = false;
  37  
  38      /**
  39       * Can the result attribute values also be boolean FALSE?
  40       *
  41       * @var    boolean
  42       * @since  4.2.0
  43       *
  44       * @deprecated 5.0 You should use nullable values or exceptions instead of returning boolean false results.
  45       */
  46      protected $resultIsFalseable = false;
  47  
  48      /**
  49       * Acceptable class names for result values.
  50       *
  51       * @var    array
  52       * @since  4.2.0
  53       */
  54      protected $resultAcceptableClasses = [];
  55  
  56      /**
  57       * Checks the type of the data being appended to the result argument.
  58       *
  59       * @param   mixed  $data  The data to type check
  60       *
  61       * @return  void
  62       * @throws  InvalidArgumentException
  63       *
  64       * @internal
  65       * @since   4.2.0
  66       */
  67      public function typeCheckResult($data): void
  68      {
  69          if ($this->resultIsNullable && $data === null) {
  70              return;
  71          }
  72  
  73          if ($this->resultIsFalseable && $data === false) {
  74              return;
  75          }
  76  
  77          if (!is_object($data)) {
  78              throw new InvalidArgumentException(sprintf('Event %s only accepts object results.', $this->getName()));
  79          }
  80  
  81          if (empty($this->resultAcceptableClasses)) {
  82              return;
  83          }
  84  
  85          foreach ($this->resultAcceptableClasses as $className) {
  86              if (is_a($data, $className)) {
  87                  return;
  88              }
  89          }
  90  
  91          $acceptableTypes = implode(', ', $this->resultAcceptableClasses);
  92          $messageTemplate = 'Event %s only accepts object results which are instances of one of %s.';
  93          throw new InvalidArgumentException(sprintf($messageTemplate, $this->getName(), $acceptableTypes));
  94      }
  95  }