[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Joomla! Content Management System
   5   *
   6   * @copyright  (C) 2020 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\MVC\View\Event;
  11  
  12  use BadMethodCallException;
  13  use Joomla\CMS\Event\AbstractImmutableEvent;
  14  
  15  // phpcs:disable PSR1.Files.SideEffects
  16  \defined('_JEXEC') or die;
  17  // phpcs:enable PSR1.Files.SideEffects
  18  
  19  /**
  20   * Event for getting extra API Fields and Relations to render with an entity
  21   *
  22   * @since  4.0.0
  23   */
  24  final class OnGetApiFields extends AbstractImmutableEvent
  25  {
  26      /**
  27       * List of types of view supported
  28       *
  29       * @since  4.0.0
  30       */
  31      public const LIST = 'list';
  32  
  33      /**
  34       * List of types of view supported
  35       *
  36       * @since  4.0.0
  37       */
  38      public const ITEM = 'item';
  39  
  40      /**
  41       * List of names of properties that will be rendered as relations
  42       *
  43       * @var    string[]
  44       * @since  4.0.0
  45       */
  46      private $extraRelations = [];
  47  
  48      /**
  49       * List of names of properties that will be rendered as data
  50       *
  51       * @var    string[]
  52       * @since  4.0.0
  53       */
  54      private $extraAttributes = [];
  55  
  56      /**
  57       * Constructor.
  58       *
  59       * Mandatory arguments:
  60       * type         string          The type of the field. Should be a constant from static::VIEW_TYPE
  61       * fields       fields          The list of fields that will be rendered in the API.
  62       *
  63       * @param   string  $name       The event name.
  64       * @param   array   $arguments  The event arguments.
  65       *
  66       * @throws  BadMethodCallException
  67       */
  68      public function __construct($name, array $arguments = array())
  69      {
  70          if (!\array_key_exists('type', $arguments)) {
  71              throw new BadMethodCallException("Argument 'type' is required for event $name");
  72          }
  73  
  74          if (!\array_key_exists('fields', $arguments)) {
  75              throw new BadMethodCallException("Argument 'fields' is required for event $name");
  76          }
  77  
  78          if (!\array_key_exists('context', $arguments)) {
  79              throw new BadMethodCallException("Argument 'context' is required for event $name");
  80          }
  81  
  82          parent::__construct($name, $arguments);
  83      }
  84  
  85      /**
  86       * Setter for the type argument
  87       *
  88       * @param   integer  $value  The constant from VIEW_TYPE
  89       *
  90       * @return  mixed
  91       *
  92       * @throws  BadMethodCallException  if the argument is not of the expected type
  93       */
  94      protected function setType($value)
  95      {
  96          if (!in_array($value, [static::ITEM, static::LIST])) {
  97              throw new BadMethodCallException("Argument 'type' of event {$this->name} must be a valid value");
  98          }
  99  
 100          return $value;
 101      }
 102  
 103      /**
 104       * Setter for the fields argument
 105       *
 106       * @param   mixed  $value  The value to set
 107       *
 108       * @return  array
 109       *
 110       * @throws  BadMethodCallException  if the argument is not a non-empty array
 111       */
 112      protected function setFields($value)
 113      {
 114          if (!\is_array($value) || is_array($value) && empty($value)) {
 115              throw new BadMethodCallException("Argument 'fields' of event {$this->name} must be be an array and not empty");
 116          }
 117  
 118          return $value;
 119      }
 120  
 121      /**
 122       * Setter for the relations argument
 123       *
 124       * @param   mixed  $value  The value to set
 125       *
 126       * @return  array
 127       *
 128       * @throws  BadMethodCallException  if the argument is not a non-empty array
 129       */
 130      protected function setRelations($value)
 131      {
 132          if (!\is_array($value)) {
 133              throw new BadMethodCallException("Argument 'relations' of event {$this->name} must be be an array");
 134          }
 135  
 136          return $value;
 137      }
 138  
 139      /**
 140       * Allows the user to add names of properties that will be interpreted as relations
 141       * Note that if there is an existing data property it will also be displayed as well
 142       * as the relation due to the internal implementation (this behaviour is not part of this API
 143       * however and should not be guaranteed)
 144       *
 145       * @param   string[]  $fields  The array of additional fields to add to the data of the attribute
 146       *
 147       * @return  void
 148       */
 149      public function addFields(array $fields): void
 150      {
 151          $this->extraAttributes = array_merge($this->extraAttributes, $fields);
 152      }
 153  
 154      /**
 155       * Allows the user to add names of properties that will be interpreted as relations
 156       * Note that if there is an existing data property it will also be displayed as well
 157       * as the relation due to the internal implementation (this behaviour is not part of this API
 158       * however and should not be guaranteed)
 159       *
 160       * @param   string[]  $fields  The array of additional fields to add as relations
 161       *
 162       * @return  void
 163       */
 164      public function addRelations(array $fields): void
 165      {
 166          $this->extraRelations = array_merge($this->extraRelations, $fields);
 167      }
 168  
 169      /**
 170       * Get properties to render.
 171       *
 172       * @return  array
 173       */
 174      public function getAllPropertiesToRender(): array
 175      {
 176          return array_merge($this->getArgument('fields'), $this->extraAttributes);
 177      }
 178  
 179      /**
 180       * Get properties to render.
 181       *
 182       * @return  array
 183       */
 184      public function getAllRelationsToRender(): array
 185      {
 186          return array_merge($this->getArgument('relations'), $this->extraRelations);
 187      }
 188  }