[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Joomla! Content Management System
   5   *
   6   * @copyright  (C) 2012 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\Feed;
  11  
  12  use Joomla\CMS\Date\Date;
  13  
  14  // phpcs:disable PSR1.Files.SideEffects
  15  \defined('JPATH_PLATFORM') or die;
  16  // phpcs:enable PSR1.Files.SideEffects
  17  
  18  /**
  19   * Class to encapsulate a feed for the Joomla Platform.
  20   *
  21   * @property  FeedPerson     $author         Person responsible for feed content.
  22   * @property  array          $categories     Categories to which the feed belongs.
  23   * @property  array          $contributors   People who contributed to the feed content.
  24   * @property  string         $copyright      Information about rights, e.g. copyrights, held in and over the feed.
  25   * @property  string         $description    A phrase or sentence describing the feed.
  26   * @property  string         $generator      A string indicating the program used to generate the feed.
  27   * @property  FeedLink|null  $image          FeedLink object containing feed image properties.
  28   * @property  Date           $publishedDate  The publication date for the feed content.
  29   * @property  string         $title          A human readable title for the feed.
  30   * @property  Date           $updatedDate    The last time the content of the feed changed.
  31   * @property  string         $uri            Universal, permanent identifier for the feed.
  32   *
  33   * @since  3.1.4
  34   */
  35  class Feed implements \ArrayAccess, \Countable
  36  {
  37      /**
  38       * @var    array  The entry properties.
  39       * @since  3.1.4
  40       */
  41      protected $properties = array(
  42          'uri' => '',
  43          'title' => '',
  44          'updatedDate' => '',
  45          'description' => '',
  46          'categories' => array(),
  47          'contributors' => array(),
  48      );
  49  
  50      /**
  51       * @var    array  The list of feed entry objects.
  52       * @since  3.1.4
  53       */
  54      protected $entries = array();
  55  
  56      /**
  57       * Magic method to return values for feed properties.
  58       *
  59       * @param   string  $name  The name of the property.
  60       *
  61       * @return  mixed
  62       *
  63       * @since   3.1.4
  64       */
  65      public function __get($name)
  66      {
  67          return $this->properties[$name] ?? null;
  68      }
  69  
  70      /**
  71       * Magic method to set values for feed properties.
  72       *
  73       * @param   string  $name   The name of the property.
  74       * @param   mixed   $value  The value to set for the property.
  75       *
  76       * @return  void
  77       *
  78       * @since   3.1.4
  79       */
  80      public function __set($name, $value)
  81      {
  82          // Ensure that setting a date always sets a Date instance.
  83          if ((($name === 'updatedDate') || ($name === 'publishedDate')) && !($value instanceof Date)) {
  84              $value = new Date($value);
  85          }
  86  
  87          // Validate that any authors that are set are instances of JFeedPerson or null.
  88          if (($name === 'author') && (!($value instanceof FeedPerson) || ($value === null))) {
  89              throw new \InvalidArgumentException(
  90                  sprintf(
  91                      '%1$s "author" must be an instance of Joomla\\CMS\\Feed\\FeedPerson. %2$s given.',
  92                      \get_class($this),
  93                      \gettype($value) === 'object' ? \get_class($value) : \gettype($value)
  94                  )
  95              );
  96          }
  97  
  98          // Disallow setting categories or contributors directly.
  99          if (\in_array($name, array('categories', 'contributors'))) {
 100              throw new \InvalidArgumentException(
 101                  sprintf(
 102                      'Cannot directly set %1$s property "%2$s".',
 103                      \get_class($this),
 104                      $name
 105                  )
 106              );
 107          }
 108  
 109          $this->properties[$name] = $value;
 110      }
 111  
 112      /**
 113       * Method to add a category to the feed object.
 114       *
 115       * @param   string  $name  The name of the category to add.
 116       * @param   string  $uri   The optional URI for the category to add.
 117       *
 118       * @return  Feed
 119       *
 120       * @since   3.1.4
 121       */
 122      public function addCategory($name, $uri = '')
 123      {
 124          $this->properties['categories'][$name] = $uri;
 125  
 126          return $this;
 127      }
 128  
 129      /**
 130       * Method to add a contributor to the feed object.
 131       *
 132       * @param   string  $name   The full name of the person to add.
 133       * @param   string  $email  The email address of the person to add.
 134       * @param   string  $uri    The optional URI for the person to add.
 135       * @param   string  $type   The optional type of person to add.
 136       *
 137       * @return  Feed
 138       *
 139       * @since   3.1.4
 140       */
 141      public function addContributor($name, $email, $uri = null, $type = null)
 142      {
 143          $contributor = new FeedPerson($name, $email, $uri, $type);
 144  
 145          // If the new contributor already exists then there is nothing to do, so just return.
 146          foreach ($this->properties['contributors'] as $c) {
 147              if ($c == $contributor) {
 148                  return $this;
 149              }
 150          }
 151  
 152          // Add the new contributor.
 153          $this->properties['contributors'][] = $contributor;
 154  
 155          return $this;
 156      }
 157  
 158      /**
 159       * Method to add an entry to the feed object.
 160       *
 161       * @param   FeedEntry  $entry  The entry object to add.
 162       *
 163       * @return  Feed
 164       *
 165       * @since   3.1.4
 166       */
 167      public function addEntry(FeedEntry $entry)
 168      {
 169          // If the new entry already exists then there is nothing to do, so just return.
 170          foreach ($this->entries as $e) {
 171              if ($e == $entry) {
 172                  return $this;
 173              }
 174          }
 175  
 176          // Add the new entry.
 177          $this->entries[] = $entry;
 178  
 179          return $this;
 180      }
 181  
 182      /**
 183       * Returns a count of the number of entries in the feed.
 184       *
 185       * This method is here to implement the Countable interface.
 186       * You can call it by doing count($feed) rather than $feed->count();
 187       *
 188       * @return  integer number of entries in the feed.
 189       */
 190      #[\ReturnTypeWillChange]
 191      public function count()
 192      {
 193          return \count($this->entries);
 194      }
 195  
 196      /**
 197       * Whether or not an offset exists.  This method is executed when using isset() or empty() on
 198       * objects implementing ArrayAccess.
 199       *
 200       * @param   mixed  $offset  An offset to check for.
 201       *
 202       * @return  boolean
 203       *
 204       * @see     ArrayAccess::offsetExists()
 205       * @since   3.1.4
 206       */
 207      #[\ReturnTypeWillChange]
 208      public function offsetExists($offset)
 209      {
 210          return isset($this->entries[$offset]);
 211      }
 212  
 213      /**
 214       * Returns the value at specified offset.
 215       *
 216       * @param   mixed  $offset  The offset to retrieve.
 217       *
 218       * @return  mixed  The value at the offset.
 219       *
 220       * @see     ArrayAccess::offsetGet()
 221       * @since   3.1.4
 222       */
 223      #[\ReturnTypeWillChange]
 224      public function offsetGet($offset)
 225      {
 226          return $this->entries[$offset];
 227      }
 228  
 229      /**
 230       * Assigns a value to the specified offset.
 231       *
 232       * @param   mixed      $offset  The offset to assign the value to.
 233       * @param   FeedEntry  $value   The JFeedEntry to set.
 234       *
 235       * @return  boolean
 236       *
 237       * @see     ArrayAccess::offsetSet()
 238       * @since   3.1.4
 239       * @throws  \InvalidArgumentException
 240       */
 241      #[\ReturnTypeWillChange]
 242      public function offsetSet($offset, $value)
 243      {
 244          if (!($value instanceof FeedEntry)) {
 245              throw new \InvalidArgumentException(
 246                  sprintf(
 247                      '%1$s entries must be an instance of Joomla\\CMS\\Feed\\FeedPerson. %2$s given.',
 248                      \get_class($this),
 249                      \gettype($value) === 'object' ? \get_class($value) : \gettype($value)
 250                  )
 251              );
 252          }
 253  
 254          $this->entries[$offset] = $value;
 255  
 256          return true;
 257      }
 258  
 259      /**
 260       * Unsets an offset.
 261       *
 262       * @param   mixed  $offset  The offset to unset.
 263       *
 264       * @return  void
 265       *
 266       * @see     ArrayAccess::offsetUnset()
 267       * @since   3.1.4
 268       */
 269      #[\ReturnTypeWillChange]
 270      public function offsetUnset($offset)
 271      {
 272          unset($this->entries[$offset]);
 273      }
 274  
 275      /**
 276       * Method to remove a category from the feed object.
 277       *
 278       * @param   string  $name  The name of the category to remove.
 279       *
 280       * @return  Feed
 281       *
 282       * @since   3.1.4
 283       */
 284      public function removeCategory($name)
 285      {
 286          unset($this->properties['categories'][$name]);
 287  
 288          return $this;
 289      }
 290  
 291      /**
 292       * Method to remove a contributor from the feed object.
 293       *
 294       * @param   FeedPerson  $contributor  The person object to remove.
 295       *
 296       * @return  Feed
 297       *
 298       * @since   3.1.4
 299       */
 300      public function removeContributor(FeedPerson $contributor)
 301      {
 302          // If the contributor exists remove it.
 303          foreach ($this->properties['contributors'] as $k => $c) {
 304              if ($c == $contributor) {
 305                  unset($this->properties['contributors'][$k]);
 306                  $this->properties['contributors'] = array_values($this->properties['contributors']);
 307  
 308                  return $this;
 309              }
 310          }
 311  
 312          return $this;
 313      }
 314  
 315      /**
 316       * Method to remove an entry from the feed object.
 317       *
 318       * @param   FeedEntry  $entry  The entry object to remove.
 319       *
 320       * @return  Feed
 321       *
 322       * @since   3.1.4
 323       */
 324      public function removeEntry(FeedEntry $entry)
 325      {
 326          // If the entry exists remove it.
 327          foreach ($this->entries as $k => $e) {
 328              if ($e == $entry) {
 329                  unset($this->entries[$k]);
 330                  $this->entries = array_values($this->entries);
 331  
 332                  return $this;
 333              }
 334          }
 335  
 336          return $this;
 337      }
 338  
 339      /**
 340       * Shortcut method to set the author for the feed object.
 341       *
 342       * @param   string  $name   The full name of the person to set.
 343       * @param   string  $email  The email address of the person to set.
 344       * @param   string  $uri    The optional URI for the person to set.
 345       * @param   string  $type   The optional type of person to set.
 346       *
 347       * @return  Feed
 348       *
 349       * @since   3.1.4
 350       */
 351      public function setAuthor($name, $email, $uri = null, $type = null)
 352      {
 353          $author = new FeedPerson($name, $email, $uri, $type);
 354  
 355          $this->properties['author'] = $author;
 356  
 357          return $this;
 358      }
 359  
 360      /**
 361       * Method to reverse the items if display is set to 'oldest first'
 362       *
 363       * @return  Feed
 364       *
 365       * @since   3.1.4
 366       */
 367      public function reverseItems()
 368      {
 369          if (\is_array($this->entries) && !empty($this->entries)) {
 370              $this->entries = array_reverse($this->entries);
 371          }
 372  
 373          return $this;
 374      }
 375  }