item_property

(ReachRSS >= 0.91)
item_property -- Get the string value of an item's property

Description

string item_property ( string channel_url , string item_id , string property_name )

Returns the value of the requested property_name from the specified item_id in the specified channel_url. If either the channel_url or item_id are invalid, item_property() will return false. If the channel_url and item_id are valid, but the property you're requesting for that item does not exist, item_property() will return NULL.

Note that ReachRSS must already be subscribed to channel_url or this function will return false. To obtain a list of subscribed channels use the function channels() or check if the channel already exists using channel_exists(). To obtain a list of valid item_id's for a particular channel, use item_ids() or check that the item id is valid using item_exists().

Here is a complete list of item properties that ReachRSS supports (as of the latest version). Note that this list is CaSe SeNsItIvE (title is valid, Title is not). Also note that simply because ReachRSS supports a property, does not mean that the channel or item you are retrieving a value from supports or lists that value. A return value of NULL means the item is there but does not list the property you are trying to retrieve.

title   The value contained within the item's <title> element. This value is the title for the item.
eg: (string) "IMterview With Bluetooth Hacking Flexilis's John Hering"
link   The value contained within the item's <link> element. This value is a web hyperlink and points to the location of the item.
eg: (string) "http://click.comicalert.com/userfriendly/6380"
guid       The value contained withing the item's <guid> element. This is the item's Globally Unique ID (if any). Note that this value is not always a web address (see example below and guid:isPermaLink, also below).
eg: (string) "http://click.comicalert.com/userfriendly/6380" or "19057@http://www.gizmodo.com/"
guid:isPermaLink   The value contained within the item's <guid isPermaLink""> element. This is a true/false boolean value that tells if the guid (above) is a valid hyperlink or not.
eg: (boolean) true
description   The value contained within the item's <description> element. This is a short (or long) description for the item and is usually a brief introduction to the article or news story that this RSS item refers to.
eg: (string) "Thousands of Bluetooth phones are vulnerable to hacking, researchers warn, allowing attackers to steal phone book data and text messages -- and even turn the phones into bugs to surreptitiously listen to conversations. By Kim Zetter."
TimeReceived   The time that the item was entered into the ReachRSS cache. This is a Unix Timestamp suitable for use with PHP's date() function.
eg: (int) 1091867662
pubDate   The value contained in the item's <pubDate> element. This field (if available) will be the last time the item was updated, and is a raw string date/time (not adjusted to your timezone).
eg: (string) "Fri, 6 Aug 2004 08:14:44 GMT"
dc:date   The value contained in the item's <dc:date> element. Since Dublin Code date elements are so widely used, ReachRSS supports both. This value (if available) is the last time the channel was updated, and is a raw string date/time (not adjusted to your timezone).
eg: (string) "2004-07-21T05:10:00+00:00"
timestamp   This value is calculated from either pubDate or dc:date and is the Unix Timestamp value for the time the item was last updated. This value is suitable for use in PHP's date() function.
eg: (int) 1091867662
category   The value contained within the item's <category> element. This value allows items to be sorted by category - ReachRSS does not currently use this value but makes it available.
category:domain   The value contained within the item's <category domain="" > element. ReachRSS does not currently use this value but makes it available.
     

Example 1. item_property() example

$ReachRSS = new ReachRSS();
$ReachRSS->Startup();
$ReachRSS->add_channel("http://www.comicalert.com/public/popular24.xml");
$ItemIDs = $ReachRSS->item_ids("http://www.comicalert.com/public/popular24.xml");
foreach ($ItemIDs as $ItemID) {
  $ItemTitle = $ReachRSS->item_property(
                       "http://www.comicalert.com/public/popular24.xml",
                       $ItemID,
                       "title"
                      );
  print "$ItemTitle\n";
}

This example will subscribe ReachRSS to the "most popular comics" feed at Comic Alert!, and then retrieve the title of each available item and print it.

Be careful not to confuse "" with NULL with FALSE. Here's how to tell the difference (notice the three equal signs (===) instead of usual two):

$GUID = $ReachRSS->item_property($ChannelURL,$ItemID,"guid");
if ($GUID===FALSE) {
  // either the $ChannelURL or $ItemID we specified was invalid
  exit;
}
if ($GUID===NULL) {
  // item exists but does not contain a guid element
  exit;
}
if ($GUID==="") {
  // the $ChannelURL and $ItemID were valid, and the guid element exists,
  // but the value is empty
  exit;
}

See also channels(), item_ids(), channel_property(), item_exists(), channel_exists()

Back to Function List

 

Home | Features | Samples | Demo | Download | Register | Help / Support