Author: as
Date: Tue Oct 9 16:25:38 2007
New Revision: 6401
Log:
- Added doc blocks for feed processors.
Modified:
trunk/Feed/src/processors/atom.php
trunk/Feed/src/processors/rss.php
trunk/Feed/src/processors/rss1.php
trunk/Feed/src/processors/rss2.php
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 16:25:38 2007
@@ -20,7 +20,7 @@
/**
* Defines the feed type of this processor.
*/
- const FEED_TYPE = 'rss1';
+ const FEED_TYPE = 'atom';
/**
* Creates a new ATOM processor.
@@ -30,36 +30,102 @@
$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 )
{
}
+ /**
+ * 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 )
{
}
+ /**
+ * Returns the value of the feed element $element.
+ *
+ * @param string $element The feed element
+ * @return mixed
+ */
public function getFeedElement( $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 )
{
}
+ /**
+ * 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()
{
}
+ /**
+ * 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 )
{
return false;
}
- public function parseItem( ezcFeed $feed, DOMElement $item )
+ /**
+ * 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 )
{
}
-
- 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 $item )
{
}
}
Modified: trunk/Feed/src/processors/rss.php
==============================================================================
--- trunk/Feed/src/processors/rss.php [iso-8859-1] (original)
+++ trunk/Feed/src/processors/rss.php [iso-8859-1] Tue Oct 9 16:25:38 2007
@@ -10,16 +10,51 @@
*/
/**
+ * Abstract class providing common functionality for the RSS1 and RSS2
+ * processors.
+ *
+ * Currently implemented for these feed types:
+ * - RSS1 ([EMAIL PROTECTED] ezcFeedRss1})
+ * - RSS2 ([EMAIL PROTECTED] ezcFeedRss2})
+ *
* @package Feed
* @version //autogentag//
*/
abstract class ezcFeedRss extends ezcFeedProcessor implements ezcFeedParser
{
+ /**
+ * Holds the root node of the XML document being generated.
+ *
+ * @var DOMNode
+ */
protected $root;
+
+ /**
+ * Holds the channel element of the XML document being generated.
+ *
+ * @var DOMElement
+ */
protected $channel;
+
+ /**
+ * Holds the item nodes of the XML document being generated.
+ *
+ * @var array(ezcFeedItem)
+ */
protected $items = array();
+
+ /**
+ * Holds meta data for the elements of the XML document being generated.
+ *
+ * @var array(string=>array(string=>mixed))
+ */
protected $metaData = array();
+ /**
+ * Creates a root node for the XML document being generated.
+ *
+ * @param string $version The RSS version for the root node
+ */
public function createRootElement( $version )
{
$rss = $this->xml->createElement( 'rss' );
@@ -32,6 +67,13 @@
$this->root = $this->xml->appendChild( $rss );
}
+ /**
+ * Creates elements in the XML document being generated with name $element
+ * and value(s) $value.
+ *
+ * @param string $element The name of the XML element
+ * @param mixed|array(mixed) $value The value(s) for $element
+ */
public function generateMetaData( $element, $value )
{
if ( !is_array( $value ) )
@@ -45,12 +87,26 @@
}
}
+ /**
+ * Sets the namespace attribute in the XML document being generated.
+ *
+ * @param string $prefix The prefix to use
+ * @param string $namespace The namespace to use
+ */
public function generateNamespace( $prefix, $namespace )
{
$this->root->setAttributeNS( "http://www.w3.org/2000/xmlns/";,
"xmlns:$prefix", $namespace );
}
- public function generateItemData( $item, $element, $value )
+ /**
+ * Creates elements in the node $item of the XML document being generated,
+ * with name $element and with value(s) $value.
+ *
+ * @param DOMNode $item The node where to add $element
+ * @param string $element The name of the XML element
+ * @param mixed|array(mixed) $value The value(s) for $element
+ */
+ public function generateItemData( DOMNode $item, $element, $value )
{
if ( !is_array( $value ) )
{
@@ -63,7 +119,16 @@
}
}
- public function generateItemDataWithAttributes( $item, $element, $value,
$attributes )
+ /**
+ * Creates elements in the node $item of the XML document being generated,
+ * with name $element and with value(s) $value and attributes $attributes.
+ *
+ * @param DOMNode $item The node where to add $element
+ * @param string $element The name of the XML element
+ * @param mixed|array(mixed) $value The value(s) for $element
+ * @param array(string=>mixed) $attributes The attributes for $element
+ */
+ public function generateItemDataWithAttributes( DOMNode $item, $element,
$value, $attributes )
{
if ( !is_array( $value ) )
{
@@ -83,7 +148,17 @@
}
}
- public function generateImage( $item, $title, $link, $imageUrl )
+ /**
+ * Creates an image element in the node $item of the XML document being
+ * generated, with the title, link and url subnodes populated with the
+ * values $title, $link and $imageUrl, respectively.
+ *
+ * @param DOMNode $item The node where to add the image element
+ * @param string $title The title of the image element
+ * @param string $link The link of the image element
+ * @param string $imageUrl The image URL of the image element
+ */
+ public function generateImage( DOMNode $item, $title, $link, $imageUrl )
{
$image = $this->xml->createElement( 'image' );
$title = $this->xml->createElement( 'title', $title );
@@ -95,6 +170,12 @@
$item->appendChild( $image );
}
+ /**
+ * Returns the provided $date in timestamp format.
+ *
+ * @param mixed $date A date
+ * @return int
+ */
public function prepareDate( $date )
{
if ( is_int( $date ) || is_numeric( $date ) )
@@ -109,11 +190,14 @@
return time();
}
- public function addItem( $item )
- {
- $this->items[] = $item;
- }
-
+ /**
+ * Returns the name on which $attributeName is mapped in the $mappingArray
+ * array, or $attributeName if a mapping does not exist for $attributeName.
+ *
+ * @param string $attributeName The attribute name
+ * @param array(string=>string) $mappingArray A mapping of attribute names
to normalized names
+ * @return string
+ */
protected function normalizeName( $attributeName, $mappingArray )
{
if ( array_key_exists( $attributeName, $mappingArray ) )
@@ -123,16 +207,29 @@
return $attributeName;
}
+ /**
+ * Returns the name on which $attributeName is mapped in the $mappingArray
+ * flipped array, or $attributeName if a mapping does not exist for
+ * $attributeName.
+ *
+ * @param string $attributeName The attribute name
+ * @param array(string=>string) $mappingArray A mapping of attribute names
to normalized names
+ * @return string
+ */
protected function deNormalizeName( $attributeName, $mappingArray )
{
return $this->normalizeName( $attributeName, array_flip( $mappingArray
) );
}
- public function getItems()
- {
- return $this->items;
- }
-
+ /**
+ * Sets the meta data associated with the XML element name $element to
$value.
+ *
+ * @throws ezcFeedOnlyOneValueAllowedException
+ * If $value is an array.
+ *
+ * @param string $element The XML element name
+ * @param mixed $value The new value for $element
+ */
public function setMetaData( $element, $value )
{
if ( is_array( $value ) )
@@ -142,6 +239,14 @@
$this->metaData[$element] = $value;
}
+ /**
+ * Adds $value to the array of meta data associated with the XML element
+ * name $element. If $value is an array it is assigned directly to the
+ * meta data, clearing old values.
+ *
+ * @param string $element The XML element name
+ * @param mixed $value The new value for $element
+ */
public function setMetaArrayData( $element, $value )
{
if ( is_array( $value ) )
@@ -158,11 +263,23 @@
}
}
+ /**
+ * Clears the meta data associated with the XML element name $element.
+ *
+ * @param string $element The XML element name
+ */
public function unsetMetaData( $element )
{
unset( $this->metaData[$element] );
}
+ /**
+ * Returns the meta data stored in this processor for the XML element name
+ * $element.
+ *
+ * @param string $element The XML element name
+ * @return array(string=>mixed)
+ */
public function getMetaData( $element )
{
if ( isset( $this->metaData[$element] ) )
@@ -172,9 +289,34 @@
return null;
}
+ /**
+ * Returns the meta data stored in this processor.
+ *
+ * @return array(string=>array(string=>mixed))
+ */
protected function getAllMetaData()
{
return $this->metaData;
+ }
+
+ /**
+ * Adds a new feed item to this processor.
+ *
+ * @param ezcFeedItem $item The feed item object to add
+ */
+ public function addItem( ezcFeedItem $item )
+ {
+ $this->items[] = $item;
+ }
+
+ /**
+ * Returns the feed items in this processor.
+ *
+ * @return array(ezcFeedItem)
+ */
+ public function getItems()
+ {
+ return $this->items;
}
}
?>
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 16:25:38 2007
@@ -10,6 +10,8 @@
*/
/**
+ * Class providing parsing and generating of RSS1 feeds.
+ *
* @package Feed
* @version //autogentag//
*/
@@ -21,6 +23,13 @@
const FEED_TYPE = 'rss1';
/**
+ * Holds a list of modules that are supported by this feed type.
+ *
+ * @var array(string)
+ */
+ protected $supportedModules = array();
+
+ /**
* Creates a new RSS1 processor.
*/
public function __construct()
@@ -28,38 +37,102 @@
$this->feedType = self::FEED_TYPE;
}
- protected $supportedModules = array();
-
+ /**
+ * 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 )
{
}
+ /**
+ * 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 )
{
}
+ /**
+ * Returns the value of the feed element $element.
+ *
+ * @param string $element The feed element
+ * @return mixed
+ */
public function getFeedElement( $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 )
{
}
+ /**
+ * 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()
{
}
+ /**
+ * 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 )
{
return false;
}
+ /**
+ * 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 )
{
return false;
}
+ /**
+ * 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/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 16:25:38 2007
@@ -114,17 +114,20 @@
public function setFeedElement( $element, $value )
{
$this->processModuleFeedSetHook( $this, $element, $value );
- if ( in_array( $element, self::$requiredFeedAttributes ) || in_array(
$element, self::$optionalFeedAttributes ) )
+ if ( in_array( $element, self::$requiredFeedAttributes )
+ || in_array( $element, self::$optionalFeedAttributes ) )
{
switch ( $element )
{
case 'category':
$this->setMetaArrayData( $element, $value );
break;
+
case 'published':
case 'updated':
$this->setMetaData( $element, $this->prepareDate( $value )
);
break;
+
default:
$this->setMetaData( $element, $value );
}
@@ -144,16 +147,19 @@
public function setFeedItemElement( ezcFeedItem $item, $element, $value )
{
$this->processModuleItemSetHook( $item, $element, $value );
- if ( in_array( $element, self::$requiredFeedItemAttributes ) ||
in_array( $element, self::$optionalFeedItemAttributes ) )
+ if ( in_array( $element, self::$requiredFeedItemAttributes )
+ || in_array( $element, self::$optionalFeedItemAttributes ) )
{
switch ( $element )
{
case 'category':
$item->setMetaArrayData( $element, $value );
break;
+
case 'published':
$item->setMetaData( $element, $this->prepareDate( $value )
);
break;
+
default:
$item->setMetaData( $element, $value );
}
@@ -222,14 +228,17 @@
{
if ( !is_null( $metaData ) )
{
- switch ( $attribute ) {
+ switch ( $attribute )
+ {
case 'guid':
$permalink = substr( $metaData, 0, 7 ) ===
'http://' ? "true" : "false";
$this->generateItemDataWithAttributes( $itemTag,
$normalizedAttribute, $metaData, array( 'isPermaLink' => $permalink ) );
break;
+
case 'published':
$this->generateItemData( $itemTag,
$normalizedAttribute, date( 'D, d M Y H:i:s O', $metaData ) );
break;
+
default:
$this->generateItemData( $itemTag,
$normalizedAttribute, $metaData );
}
@@ -294,10 +303,12 @@
case 'image':
$this->generateImage( $this->channel,
$this->getMetaData( 'title' ), $this->getMetaData( 'link' ), $data );
break;
+
case 'published':
case 'updated':
$this->generateMetaData( $normalizedAttribute,
date( 'D, d M Y H:i:s O', $data ) );
break;
+
default:
$this->generateMetaData( $normalizedAttribute,
$data );
}
@@ -351,56 +362,6 @@
}
/**
- * 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 )
- {
- if ( $itemChild->nodeType == XML_ELEMENT_NODE )
- {
- $tagName = $itemChild->tagName;
- $tagName = $this->deNormalizeName( $tagName,
self::$feedItemAttributesMap );
- switch ( $tagName )
- {
- case 'title':
- case 'link':
- case 'description':
- case 'author':
- case 'comments':
- case 'enclosure':
- case 'guid':
- case 'source':
- $feedItem->$tagName = $itemChild->textContent;
- break;
- case 'published':
- $feedItem->$tagName = $this->prepareDate(
$itemChild->textContent );
- break;
- case 'category':
- $array = $feedItem->$tagName;
- $array[] = $itemChild->textContent;
- $feedItem->$tagName = $array;
- break;
- default:
- // check if it's part of a known module/namespace
- $parts = explode( ':', $tagName );
- if ( count( $parts ) == 2 && in_array( $parts[0],
array_keys( $this->usedPrefixes ) ) )
- {
- $moduleName = $this->usedPrefixes[$parts[0]];
- $element = $parts[1];
- $feedItem->$moduleName->$element =
$itemChild->textContent;
- }
- }
- }
- }
- }
-
- /**
* Parses the provided XML document object and returns an ezcFeed object
* from it.
*
@@ -412,7 +373,7 @@
*/
public function parse( DOMDocument $xml )
{
- $feed = new ezcFeed( 'rss2' );
+ $feed = new ezcFeed( self::FEED_TYPE );
$rssChildren = $xml->documentElement->childNodes;
$channel = null;
@@ -493,5 +454,59 @@
}
return $feed;
}
+
+ /**
+ * 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 )
+ {
+ if ( $itemChild->nodeType == XML_ELEMENT_NODE )
+ {
+ $tagName = $itemChild->tagName;
+ $tagName = $this->deNormalizeName( $tagName,
self::$feedItemAttributesMap );
+
+ switch ( $tagName )
+ {
+ case 'title':
+ case 'link':
+ case 'description':
+ case 'author':
+ case 'comments':
+ case 'enclosure':
+ case 'guid':
+ case 'source':
+ $feedItem->$tagName = $itemChild->textContent;
+ break;
+
+ case 'published':
+ $feedItem->$tagName = $this->prepareDate(
$itemChild->textContent );
+ break;
+
+ case 'category':
+ $array = $feedItem->$tagName;
+ $array[] = $itemChild->textContent;
+ $feedItem->$tagName = $array;
+ break;
+
+ default:
+ // check if it's part of a known module/namespace
+ $parts = explode( ':', $tagName );
+ if ( count( $parts ) == 2 && in_array( $parts[0],
array_keys( $this->usedPrefixes ) ) )
+ {
+ $moduleName = $this->usedPrefixes[$parts[0]];
+ $element = $parts[1];
+ $feedItem->$moduleName->$element =
$itemChild->textContent;
+ }
+ }
+ }
+ }
+ }
}
?>
--
svn-components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/svn-components
