Author: as
Date: Tue Oct 9 14:11:47 2007
New Revision: 6400
Log:
- Added type hinting for some methods.
- DomDocument -> DOMDocument.
- Added doc blocks for Parser, Processor and Rss2 classes.
Modified:
trunk/Feed/src/feed.php
trunk/Feed/src/interfaces/parser.php
trunk/Feed/src/interfaces/processor.php
trunk/Feed/src/processors/atom.php
trunk/Feed/src/processors/rss1.php
trunk/Feed/src/processors/rss2.php
Modified: trunk/Feed/src/feed.php
==============================================================================
--- trunk/Feed/src/feed.php [iso-8859-1] (original)
+++ trunk/Feed/src/feed.php [iso-8859-1] Tue Oct 9 14:11:47 2007
@@ -251,8 +251,11 @@
case 'items':
throw new ezcBasePropertyPermissionException( $property,
ezcBasePropertyPermissionException::READ );
- }
-
+
+ default:
+ }
+
+ // @todo find a way to remove this from here
$modules = $this->feedProcessor->getModules();
foreach ( $modules as $moduleName => $moduleObj )
{
Modified: trunk/Feed/src/interfaces/parser.php
==============================================================================
--- trunk/Feed/src/interfaces/parser.php [iso-8859-1] (original)
+++ trunk/Feed/src/interfaces/parser.php [iso-8859-1] Tue Oct 9 14:11:47 2007
@@ -10,13 +10,46 @@
*/
/**
+ * Interface for feed parsers.
+ *
+ * Currently implemented for these feed types:
+ * - RSS1 ([EMAIL PROTECTED] ezcFeedRss1})
+ * - RSS2 ([EMAIL PROTECTED] ezcFeedRss2})
+ * - ATOM ([EMAIL PROTECTED] ezcFeedAtom})
+ *
* @package Feed
* @version //autogentag//
*/
interface ezcFeedParser
{
- public static function canParse( DomDocument $xml );
- public function parse( DomDocument $xml );
- public function parseItem( ezcFeed $feed, DomElement $xml );
+ /**
+ * Returns true if the parser can parse the provided XML document object,
+ * false otherwise.
+ *
+ * @param DOMDocument $xml The XML document object to check for
parseability
+ * @return bool
+ */
+ public static function canParse( DOMDocument $xml );
+
+ /**
+ * Parses the provided XML document object and returns an ezcFeed object
+ * from it.
+ *
+ * @throws ezcFeedParseErrorException
+ * If an error was encountered during parsing.
+ *
+ * @param DOMDocument $xml The XML document object to parse
+ * @return ezcFeed
+ */
+ public function parse( DOMDocument $xml );
+
+ /**
+ * Parses the provided XML element object and stores it as a feed item in
+ * the provided ezcFeed object.
+ *
+ * @param ezcFeed $feed The feed object in which to store the parsed XML
element as a feed item
+ * @param DOMElement $xml The XML element object to parse
+ */
+ public function parseItem( ezcFeed $feed, DOMElement $xml );
}
?>
Modified: trunk/Feed/src/interfaces/processor.php
==============================================================================
--- trunk/Feed/src/interfaces/processor.php [iso-8859-1] (original)
+++ trunk/Feed/src/interfaces/processor.php [iso-8859-1] Tue Oct 9 14:11:47
2007
@@ -39,7 +39,7 @@
protected $feedType;
/**
- * A list of modules which are loaded.
+ * A list of modules contained in this processor.
*
* @var array(string=>ezcFeedModuleData)
* @ignore
@@ -65,6 +65,14 @@
protected $moduleMetaData = array();
/**
+ * Holds the XML document which is being generated.
+ *
+ * @var DOMDocument
+ * @ignore
+ */
+ protected $xml;
+
+ /**
* Returns the type of this processor (eg. 'rss1').
*
* @return string
@@ -108,24 +116,61 @@
return $this->modules[$moduleName];
}
+ /**
+ * Adds a new module named $moduleName to the feed processor in $item.
+ *
+ * @throws ezcFeedUnsupportedModuleException
+ * If the module is not supported by this feed processor.
+ *
+ * @param string $moduleName The type of the module
+ * @param ezcFeedModule $moduleObj The instance of the module
+ * @param ezcFeedItem $item The instance of the feed item
+ * @return ezcFeedItemModuleData
+ */
public function addItemModule( $moduleName, $moduleObj, $item )
{
if ( !$this->isModuleSupported( $moduleName ) )
{
throw new ezcFeedUnsupportedModuleException( $moduleName );
}
+
return new ezcFeedItemModuleData( $moduleName, $moduleObj, $item );
}
- public function getAllModuleMetaData( $module )
- {
- if ( isset( $this->moduleMetaData[$module] ) )
- {
- return $this->moduleMetaData[$module];
+ /**
+ * Returns all the meta data for the module $moduleName.
+ *
+ * The format of the returned array is:
+ * <code>
+ * array( element_name => element_value );
+ * </code>
+ *
+ * Example:
+ * <code>
+ * array( 'title' => 'News', 'format' = 'text/plain' );
+ * </code>
+ *
+ * @param string $moduleName The type of the module
+ * @return array(string=>mixed)
+ */
+ public function getAllModuleMetaData( $moduleName )
+ {
+ if ( isset( $this->moduleMetaData[$moduleName] ) )
+ {
+ return $this->moduleMetaData[$moduleName];
}
return array();
}
+ /**
+ * Returns the meta data value of the element $element from the module
+ * $moduleName.
+ *
+ * @param string $moduleName The type of the module
+ * @param ezcFeedModule $moduleObj The module object
+ * @param string $element The element in the module
+ * @return mixed
+ */
public function getModuleMetaData( $moduleName, $moduleObj, $element )
{
if ( isset( $this->moduleMetaData[$moduleName][$element] ) )
@@ -135,11 +180,31 @@
return null;
}
- public function getModuleItemData( $moduleName, $moduleObj, $item,
$element )
+ /**
+ * Returns the meta data value of the provided element in the module
+ * $moduleName of the item $item.
+ *
+ * @param string $moduleName The type of the module
+ * @param ezcFeedModule $moduleObj The module object
+ * @param ezcFeedItem $item The feed item object
+ * @param string $element The element in the module
+ * @return mixed
+ */
+ public function getModuleItemData( $moduleName, $moduleObj, ezcFeedItem
$item, $element )
{
return $item->getModuleMetaData( $moduleName, $element );
}
+ /**
+ * Sets the meta data value for the element $element of the module
+ * $moduleName to $value.
+ *
+ * @param string $moduleName The type of the module
+ * @param ezcFeedModule $moduleObj The module object
+ * @param ezcFeedItem $item The feed item object
+ * @param string $element The element in the module
+ * @return mixed
+ */
public function setModuleMetaData( $moduleName, $moduleObj, $element,
$value )
{
$value = $moduleObj->prepareMetaData( $element, $value );
@@ -152,17 +217,38 @@
$item->setModuleMetaData( $moduleName, $moduleObj, $element, $value );
}
+ /**
+ * Returns the list of supported modules by this processor.
+ *
+ * @return array(string)
+ */
public function getSupportedModules()
{
return $this->supportedModules;
}
+ /**
+ * Returns the modules contained in this processor.
+ *
+ * @return array(string=>ezcFeedModuleData)
+ */
public function getModules()
{
return $this->modules;
}
- public function processModuleFeedSetHook( $feed, $element, $value )
+ /**
+ * Ensures the correct setting of element $element to $value for feed
+ * processor $feed.
+ *
+ * This hook is called before calling setMetaData() with the $element and
$value
+ * arguments for the feed processor $feed.
+ *
+ * @param ezcFeedProcessor $feed The feed processor
+ * @param string $element The name of the element to set
+ * @param mixed $value The new value for $element
+ */
+ public function processModuleFeedSetHook( ezcFeedProcessor $feed,
$element, $value )
{
foreach ( $this->modules as $moduleName => $moduleDescription )
{
@@ -174,6 +260,18 @@
}
}
+ /**
+ * Ensures the correct generation of feed element $element with value
+ * $value. Returns true if setting $element is allowed, false otherwise.
+ *
+ * This hook is called before calling generateMetaData() with the
normalized
+ * name of $element and (eventually prepared) value $value. It is called
in the
+ * generate() method of the processor implementation.
+ *
+ * @param string $element The name of the element to set
+ * @param mixed $value The new value for $element
+ * @return bool
+ */
public function processModuleFeedGenerateHook( $element, $value )
{
foreach ( $this->modules as $moduleName => $moduleDescription )
@@ -187,7 +285,18 @@
return true;
}
- public function processModuleItemSetHook( $item, $element, $value )
+ /**
+ * Ensures the correct setting of element $element to $value for feed item
+ * $item.
+ *
+ * This hook is called before calling setMetaData() with the $element and
$value
+ * arguments for the feed item $item.
+ *
+ * @param ezcFeedItem $feed The feed item object
+ * @param string $element The name of the element to set
+ * @param mixed $value The new value for $element
+ */
+ public function processModuleItemSetHook( ezcFeedItem $item, $element,
$value )
{
foreach ( $this->modules as $moduleName => $moduleDescription )
{
@@ -199,7 +308,21 @@
}
}
- public function processModuleItemGenerateHook( $item, $element, $value )
+ /**
+ * Ensures the correct generation of feed element $element with value
+ * $value in item $item. Returns true if setting $element is allowed,
+ * false otherwise.
+ *
+ * This hook is called before calling generateItemData() with the
normalized
+ * name of $element and (eventually prepared) value $value. It is called
in the
+ * generate() method of the processor implementation.
+ *
+ * @param ezcFeedItem $item The feed item object
+ * @param string $element The name of the element to set
+ * @param mixed $value The new value for $element
+ * @return bool
+ */
+ public function processModuleItemGenerateHook( ezcFeedItem $item,
$element, $value )
{
foreach ( $this->modules as $moduleName => $moduleDescription )
{
@@ -212,10 +335,56 @@
return true;
}
+ /**
+ * Sets the value of the feed element $element to $value.
+ *
+ * The hook [EMAIL PROTECTED] self::processModuleFeedSetHook()} can be
used in the
+ * implementation before setting $element.
+ *
+ * @param string $element The feed element
+ * @param mixed $value The new value of $element
+ */
+ abstract public function setFeedElement( $element, $value );
+
+ /**
+ * Sets the value of the feed element $element of feed item $item to
$value.
+ *
+ * The hook [EMAIL PROTECTED] self::processModuleItemSetHook()} can be
used in the
+ * implementation before setting $element.
+ *
+ * @param ezcFeedItem $item The feed item object
+ * @param string $element The feed element
+ * @param mixed $value The new value of $element
+ */
+ abstract public function setFeedItemElement( ezcFeedItem $item, $element,
$value );
+
+ /**
+ * Returns the value of the feed element $element.
+ *
+ * @param string $element The feed element
+ * @return mixed
+ */
abstract public function getFeedElement( $element );
- abstract public function getFeedItemElement( $item, $element );
- abstract public function setFeedElement( $element, $value );
- abstract public function setFeedItemElement( $item, $element, $value );
+
+ /**
+ * Returns the value of the element $element of feed item $item.
+ *
+ * @param ezcFeedItem $item The feed item object
+ * @param string $element The feed element
+ * @return mixed
+ */
+ abstract public function getFeedItemElement( ezcFeedItem $item, $element );
+
+ /**
+ * Returns an XML string from the feed information contained in this
+ * processor.
+ *
+ * The hooks [EMAIL PROTECTED] self::processModuleFeedGenerateHook()} and
+ * [EMAIL PROTECTED] self::processModuleItemGenerateHook()} can be used in
the
+ * implementation for each attribute in the feed and in the feed items.
+ *
+ * @return string
+ */
abstract public function generate();
}
?>
Modified: trunk/Feed/src/processors/atom.php
==============================================================================
--- trunk/Feed/src/processors/atom.php [iso-8859-1] (original)
+++ trunk/Feed/src/processors/atom.php [iso-8859-1] Tue Oct 9 14:11:47 2007
@@ -34,7 +34,7 @@
{
}
- public function setFeedItemElement( $item, $element, $value )
+ public function setFeedItemElement( ezcFeedItem $item, $element, $value )
{
}
@@ -42,7 +42,7 @@
{
}
- public function getFeedItemElement( $item, $element )
+ public function getFeedItemElement( ezcFeedItem $item, $element )
{
}
@@ -50,16 +50,16 @@
{
}
- public static function canParse( DomDocument $xml )
+ public static function canParse( DOMDocument $xml )
{
return false;
}
- public function parseItem( ezcFeed $feed, DomElement $item )
+ public function parseItem( ezcFeed $feed, DOMElement $item )
{
}
- public function parse( DomDocument $xml )
+ public function parse( DOMDocument $xml )
{
}
}
Modified: trunk/Feed/src/processors/rss1.php
==============================================================================
--- trunk/Feed/src/processors/rss1.php [iso-8859-1] (original)
+++ trunk/Feed/src/processors/rss1.php [iso-8859-1] Tue Oct 9 14:11:47 2007
@@ -34,7 +34,7 @@
{
}
- public function setFeedItemElement( $item, $element, $value )
+ public function setFeedItemElement( ezcFeedItem $item, $element, $value )
{
}
@@ -42,7 +42,7 @@
{
}
- public function getFeedItemElement( $item, $element )
+ public function getFeedItemElement( ezcFeedItem $item, $element )
{
}
@@ -50,17 +50,17 @@
{
}
- public static function canParse( DomDocument $xml )
+ public static function canParse( DOMDocument $xml )
{
return false;
}
- public function parse( DomDocument $xml )
+ public function parse( DOMDocument $xml )
{
return false;
}
- public function parseItem( ezcFeed $feed, DomElement $xml )
+ public function parseItem( ezcFeed $feed, DOMElement $xml )
{
}
}
Modified: trunk/Feed/src/processors/rss2.php
==============================================================================
--- trunk/Feed/src/processors/rss2.php [iso-8859-1] (original)
+++ trunk/Feed/src/processors/rss2.php [iso-8859-1] Tue Oct 9 14:11:47 2007
@@ -10,6 +10,8 @@
*/
/**
+ * Class providing parsing and generating of RSS2 feeds.
+ *
* @package Feed
* @version //autogentag//
*/
@@ -21,21 +23,21 @@
const FEED_TYPE = 'rss2';
/**
- * A list of modules that are supported by this feed type
+ * Holds a list of modules that are supported by this feed type.
*
* @var array(string)
*/
protected $supportedModules = array( 'DublinCore', 'Content' );
/**
- * A list of required attributes for the channel definition.
+ * Holds a list of required attributes for the channel definition.
*
* @var array(string)
*/
protected static $requiredFeedAttributes = array( 'title', 'link',
'description' );
/**
- * A list of optional attributes for the channel definition.
+ * Holds a list of optional attributes for the channel definition.
*
* @var array(string)
*/
@@ -44,7 +46,8 @@
'category', 'generator', 'ttl', 'docs', 'image' );
/**
- * This array maps the common names for channel attributes to feed
specific names
+ * Holds a mapping of the common names for channel attributes to feed
specific
+ * names.
*
* @var array(string=>string)
*/
@@ -54,13 +57,37 @@
'updated' => 'lastBuildDate',
);
+ /**
+ * Holds a list of required attributes for items definitions.
+ *
+ * @var array(string)
+ */
protected static $requiredFeedItemAttributes = array( 'title', 'link',
'description' );
+
+ /**
+ * Holds a list of optional attributes for items definitions.
+ *
+ * @var array(string)
+ */
protected static $optionalFeedItemAttributes = array( 'author', 'category',
'comments', 'enclosure', 'guid', 'published', 'source' );
+
+ /**
+ * Holds a mapping of the common names for items attributes to feed
specific
+ * names.
+ *
+ * @var array(string=>string)
+ */
protected static $feedItemAttributesMap = array(
'published' => 'pubDate',
);
+ /**
+ * Holds the prefixes used in the feed generation process.
+ *
+ * @var array(string)
+ * @ignore
+ */
protected $usedPrefixes = array();
/**
@@ -75,6 +102,15 @@
$this->feedType = self::FEED_TYPE;
}
+ /**
+ * Sets the value of the feed element $element to $value.
+ *
+ * The hook [EMAIL PROTECTED]
ezcFeedProcessor::processModuleFeedSetHook()} is called
+ * before setting $element.
+ *
+ * @param string $element The feed element
+ * @param mixed $value The new value of $element
+ */
public function setFeedElement( $element, $value )
{
$this->processModuleFeedSetHook( $this, $element, $value );
@@ -95,7 +131,17 @@
}
}
- public function setFeedItemElement( $item, $element, $value )
+ /**
+ * Sets the value of the feed element $element of feed item $item to
$value.
+ *
+ * The hook [EMAIL PROTECTED]
ezcFeedProcessor::processModuleItemSetHook()} is called
+ * before setting $element.
+ *
+ * @param ezcFeedItem $item The feed item object
+ * @param string $element The feed element
+ * @param mixed $value The new value of $element
+ */
+ public function setFeedItemElement( ezcFeedItem $item, $element, $value )
{
$this->processModuleItemSetHook( $item, $element, $value );
if ( in_array( $element, self::$requiredFeedItemAttributes ) ||
in_array( $element, self::$optionalFeedItemAttributes ) )
@@ -114,19 +160,42 @@
}
}
+ /**
+ * Returns the value of the feed element $element.
+ *
+ * @param string $element The feed element
+ * @return mixed
+ */
public function getFeedElement( $element )
{
$element = $this->normalizeName( $element, self::$feedAttributesMap );
return $this->getMetaData( $element );
}
- public function getFeedItemElement( $item, $element )
+ /**
+ * Returns the value of the element $element of feed item $item.
+ *
+ * @param ezcFeedItem $item The feed item object
+ * @param string $element The feed element
+ * @return mixed
+ */
+ public function getFeedItemElement( ezcFeedItem $item, $element )
{
$element = $this->normalizeName( $element,
self::$feedItemAttributesMap );
return $item->getMetaData( $element );
}
- protected function generateItem( $item )
+ /**
+ * Generates the required data for the feed item $item and includes it in
+ * the XML document which is being generated.
+ *
+ * The hook [EMAIL PROTECTED]
ezcFeedProcessor::processModuleItemGenerateHook()} is
+ * called for each attribute in the item.
+ *
+ * @param ezcFeedItem $item The feed item object
+ * @return string
+ */
+ protected function generateItem( ezcFeedItem $item )
{
$itemTag = $this->xml->createElement( 'item' );
$this->channel->appendChild( $itemTag );
@@ -182,9 +251,19 @@
}
}
+ /**
+ * Returns an XML string from the feed information contained in this
+ * processor.
+ *
+ * The hooks [EMAIL PROTECTED]
ezcFeedProcessor::processModuleFeedGenerateHook()} and
+ * [EMAIL PROTECTED] ezcFeedProcessor::processModuleItemGenerateHook()}
are used for
+ * each attribute in the feed and in the feed items.
+ *
+ * @return string
+ */
public function generate()
{
- $this->xml = new DomDocument( '1.0', 'utf-8' );
+ $this->xml = new DOMDocument( '1.0', 'utf-8' );
$this->xml->formatOutput = 1;
$this->createRootElement( '2.0' );
@@ -247,7 +326,14 @@
return $this->xml->saveXML();
}
- public static function canParse( DomDocument $xml )
+ /**
+ * Returns true if the parser can parse the provided XML document object,
+ * false otherwise.
+ *
+ * @param DOMDocument $xml The XML document object to check for
parseability
+ * @return bool
+ */
+ public static function canParse( DOMDocument $xml )
{
if ( $xml->documentElement->tagName !== 'rss' )
{
@@ -264,7 +350,14 @@
return true;
}
- public function parseItem( ezcFeed $feed, DomElement $item )
+ /**
+ * Parses the provided XML element object and stores it as a feed item in
+ * the provided ezcFeed object.
+ *
+ * @param ezcFeed $feed The feed object in which to store the parsed XML
element as a feed item
+ * @param DOMElement $xml The XML element object to parse
+ */
+ public function parseItem( ezcFeed $feed, DOMElement $item )
{
$feedItem = $feed->newItem();
foreach ( $item->childNodes as $itemChild )
@@ -307,7 +400,17 @@
}
}
- public function parse( DomDocument $xml )
+ /**
+ * Parses the provided XML document object and returns an ezcFeed object
+ * from it.
+ *
+ * @throws ezcFeedParseErrorException
+ * If an error was encountered during parsing.
+ *
+ * @param DOMDocument $xml The XML document object to parse
+ * @return ezcFeed
+ */
+ public function parse( DOMDocument $xml )
{
$feed = new ezcFeed( 'rss2' );
$rssChildren = $xml->documentElement->childNodes;
@@ -350,6 +453,7 @@
{
$tagName = $channelChild->tagName;
$tagName = $this->deNormalizeName( $tagName,
self::$feedAttributesMap );
+
switch ( $tagName )
{
case 'title':
@@ -365,13 +469,16 @@
case 'category':
$feed->$tagName = $channelChild->textContent;
break;
+
case 'published':
case 'updated':
$feed->$tagName = $this->prepareDate(
$channelChild->textContent );
break;
+
case 'item':
$this->parseItem( $feed, $channelChild );
break;
+
default:
// check if it's part of a known module/namespace
$parts = explode( ':', $tagName );
--
svn-components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/svn-components
