Source for file feed.php

Documentation is available at feed.php

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

Documentation generated on Tue, 19 Nov 2013 15:02:56 +0100 by phpDocumentor 1.4.3