[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 entry for the Joomla Platform.
  20   *
  21   * @property  FeedPerson  $author         Person responsible for feed entry content.
  22   * @property  array       $categories     Categories to which the feed entry belongs.
  23   * @property  string      $content        The content of the feed entry.
  24   * @property  array       $contributors   People who contributed to the feed entry content.
  25   * @property  string      $copyright      Information about rights, e.g. copyrights, held in and over the feed entry.
  26   * @property  array       $links          Links associated with the feed entry.
  27   * @property  Date        $publishedDate  The publication date for the feed entry.
  28   * @property  Feed        $source         The feed from which the entry is sourced.
  29   * @property  string      $title          A human readable title for the feed entry.
  30   * @property  Date        $updatedDate    The last time the content of the feed entry changed.
  31   * @property  string      $uri            Universal, permanent identifier for the feed entry.
  32   *
  33   * @since  3.1.4
  34   */
  35  class FeedEntry
  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          'content' => '',
  46          'categories' => array(),
  47          'contributors' => array(),
  48          'links' => array(),
  49      );
  50  
  51      /**
  52       * Magic method to return values for feed entry properties.
  53       *
  54       * @param   string  $name  The name of the property.
  55       *
  56       * @return  mixed
  57       *
  58       * @since   3.1.4
  59       */
  60      public function __get($name)
  61      {
  62          return $this->properties[$name] ?? null;
  63      }
  64  
  65      /**
  66       * Magic method to set values for feed properties.
  67       *
  68       * @param   string  $name   The name of the property.
  69       * @param   mixed   $value  The value to set for the property.
  70       *
  71       * @return  void
  72       *
  73       * @since   3.1.4
  74       */
  75      public function __set($name, $value)
  76      {
  77          // Ensure that setting a date always sets a Date instance.
  78          if ((($name === 'updatedDate') || ($name === 'publishedDate')) && !($value instanceof Date)) {
  79              $value = new Date($value);
  80          }
  81  
  82          // Validate that any authors that are set are instances of JFeedPerson or null.
  83          if (($name === 'author') && (!($value instanceof FeedPerson) || ($value === null))) {
  84              throw new \InvalidArgumentException(
  85                  sprintf(
  86                      '%1$s "author" must be an instance of Joomla\\CMS\\Feed\\FeedPerson. %2$s given.',
  87                      \get_class($this),
  88                      \gettype($value) === 'object' ? \get_class($value) : \gettype($value)
  89                  )
  90              );
  91          }
  92  
  93          // Validate that any sources that are set are instances of JFeed or null.
  94          if (($name === 'source') && (!($value instanceof Feed) || ($value === null))) {
  95              throw new \InvalidArgumentException(
  96                  sprintf(
  97                      '%1$s "source" must be an instance of Joomla\\CMS\\Feed\\Feed. %2$s given.',
  98                      \get_class($this),
  99                      \gettype($value) === 'object' ? \get_class($value) : \gettype($value)
 100                  )
 101              );
 102          }
 103  
 104          // Disallow setting categories, contributors, or links directly.
 105          if (\in_array($name, array('categories', 'contributors', 'links'))) {
 106              throw new \InvalidArgumentException(
 107                  sprintf(
 108                      'Cannot directly set %1$s property "%2$s".',
 109                      \get_class($this),
 110                      $name
 111                  )
 112              );
 113          }
 114  
 115          $this->properties[$name] = $value;
 116      }
 117  
 118      /**
 119       * Method to add a category to the feed entry object.
 120       *
 121       * @param   string  $name  The name of the category to add.
 122       * @param   string  $uri   The optional URI for the category to add.
 123       *
 124       * @return  FeedEntry
 125       *
 126       * @since   3.1.4
 127       */
 128      public function addCategory($name, $uri = '')
 129      {
 130          $this->properties['categories'][$name] = $uri;
 131  
 132          return $this;
 133      }
 134  
 135      /**
 136       * Method to add a contributor to the feed entry object.
 137       *
 138       * @param   string  $name   The full name of the person to add.
 139       * @param   string  $email  The email address of the person to add.
 140       * @param   string  $uri    The optional URI for the person to add.
 141       * @param   string  $type   The optional type of person to add.
 142       *
 143       * @return  FeedEntry
 144       *
 145       * @since   3.1.4
 146       */
 147      public function addContributor($name, $email, $uri = null, $type = null)
 148      {
 149          $contributor = new FeedPerson($name, $email, $uri, $type);
 150  
 151          // If the new contributor already exists then there is nothing to do, so just return.
 152          foreach ($this->properties['contributors'] as $c) {
 153              if ($c == $contributor) {
 154                  return $this;
 155              }
 156          }
 157  
 158          // Add the new contributor.
 159          $this->properties['contributors'][] = $contributor;
 160  
 161          return $this;
 162      }
 163  
 164      /**
 165       * Method to add a link to the feed entry object.
 166       *
 167       * @param   FeedLink  $link  The link object to add.
 168       *
 169       * @return  FeedEntry
 170       *
 171       * @since   3.1.4
 172       */
 173      public function addLink(FeedLink $link)
 174      {
 175          // If the new link already exists then there is nothing to do, so just return.
 176          foreach ($this->properties['links'] as $l) {
 177              if ($l == $link) {
 178                  return $this;
 179              }
 180          }
 181  
 182          // Add the new link.
 183          $this->properties['links'][] = $link;
 184  
 185          return $this;
 186      }
 187  
 188      /**
 189       * Method to remove a category from the feed entry object.
 190       *
 191       * @param   string  $name  The name of the category to remove.
 192       *
 193       * @return  FeedEntry
 194       *
 195       * @since   3.1.4
 196       */
 197      public function removeCategory($name)
 198      {
 199          unset($this->properties['categories'][$name]);
 200  
 201          return $this;
 202      }
 203  
 204      /**
 205       * Method to remove a contributor from the feed entry object.
 206       *
 207       * @param   FeedPerson  $contributor  The person object to remove.
 208       *
 209       * @return  FeedEntry
 210       *
 211       * @since   3.1.4
 212       */
 213      public function removeContributor(FeedPerson $contributor)
 214      {
 215          // If the contributor exists remove it.
 216          foreach ($this->properties['contributors'] as $k => $c) {
 217              if ($c == $contributor) {
 218                  unset($this->properties['contributors'][$k]);
 219                  $this->properties['contributors'] = array_values($this->properties['contributors']);
 220  
 221                  return $this;
 222              }
 223          }
 224  
 225          return $this;
 226      }
 227  
 228      /**
 229       * Method to remove a link from the feed entry object.
 230       *
 231       * @param   FeedLink  $link  The link object to remove.
 232       *
 233       * @return  FeedEntry
 234       *
 235       * @since   3.1.4
 236       */
 237      public function removeLink(FeedLink $link)
 238      {
 239          // If the link exists remove it.
 240          foreach ($this->properties['links'] as $k => $l) {
 241              if ($l == $link) {
 242                  unset($this->properties['links'][$k]);
 243                  $this->properties['links'] = array_values($this->properties['links']);
 244  
 245                  return $this;
 246              }
 247          }
 248  
 249          return $this;
 250      }
 251  
 252      /**
 253       * Shortcut method to set the author for the feed entry object.
 254       *
 255       * @param   string  $name   The full name of the person to set.
 256       * @param   string  $email  The email address of the person to set.
 257       * @param   string  $uri    The optional URI for the person to set.
 258       * @param   string  $type   The optional type of person to set.
 259       *
 260       * @return  FeedEntry
 261       *
 262       * @since   3.1.4
 263       */
 264      public function setAuthor($name, $email, $uri = null, $type = null)
 265      {
 266          $author = new FeedPerson($name, $email, $uri, $type);
 267  
 268          $this->properties['author'] = $author;
 269  
 270          return $this;
 271      }
 272  }