RSS-PHP v3 Documentation
RSS-PHP is a PHP 5 class which acts as an interface to a DOMDocument allowing easy access and conversion between array and xml.
RSS-PHP v3 Pre(R)amble
Think of this version of RSS-PHP as more of an XML-PHP; it will support all valid XML documents, including RSS and ATOM. Infact now the only RSS specific methods are getItems() and getRSS().
One major functionality change is the addition of loadArray(), which will convert any array into a DOMDocument which in-turn means Array to XML Conversion.
Another major change is that the main document interface is now an array view of the DOMDocument, including all DOMElements, allowing you to negotiate a DOMDocument as if it where an array, whilst still having all the functionality of the DOM available to you.
RSS-PHP now encourages you to interact with the document using query(), getElementsByTagName() and getValuesByTagName() as this gives you far more direct access to the values you want to return from your XML document; all returned values are Array views of the DOMElements, so you can iterate and reference them easily.
As most method returns are infact references to the internal variables, you can now quickly retrieve an item, change it and rewrite the RSS/XML using getXML().
Finally, encoding worries are now a thing of the past, as RSS-PHP will automatically detect the encoding of the document and change it to UTF-8 for you on the fly! [even if the encoding has been ommited or is incorrect]
RSS-PHP Configuration Constants
The RSS-PHP Object has 3 configuration constants.
- RSS_PHP_ENCODING_CONVERSION [default TRUE] - Should rss-php attempt to perform auto encoding detection and conversion to UTF-8.
- RSS_PHP_ICONV_UNSUPPORTED_LANG_DIE [default TRUE] - Should rss-php die if it finds an encoding unsupported by the machine.
- RSS_PHP_HTTP_TRANSPORT [default TRUE] - Should rss-php use HTTP_TRANSPORT
RSS-PHP automatically detects if the host machine supports the additional modules in v3; as such it is safe to leave them enabled at all times.
RSS-PHP Properties
The RSS-PHP Object has 7 public properties, they are included and made public purely for advanced usage and integration into RSS-PHP.
- RSS_PHP->document
Provides access to a Multidimensional, Associative Array of Objects (DOMElements) that allows you to interact with the DOMDocument as if it were an Array. - RSS_PHP->DOMDocument
Internal storage of the DOMDocument. - RSS_PHP->DOMNamespaces
Array holding all XMLNS (XML Namespaces) found in an input XML Document. - RSS_PHP->DOMProcessingInstructions
Array to hold all DOMProcessingInstructions found in an input XML Document [such as style-sheets] - RSS_PHP->DOMXPath
Preloaded Internal DOMXPath Object for use with ->query function - RSS_PHP->useXMLEncoding
Display whether RSS-PHP is using the included encoding_xml and encoding_iconv libraries - RSS_PHP->useHTTPTransport
Display whether RSS-PHP is using the included http_handler library
RSS_PHP->load()
RSS_PHP->load(string $url, string $user, string $pass) - load a local or remote XML / RSS document into the RSS-PHP Object
if RSS_PHP_HTTP_TRANSPORT is TRUE [default] then RSS_PHP will attempt to immitate a user-agent to prevent the HTTP Request from being blocked.
$user and $pass are only supported when RSS_PHP_HTTP_TRANSPORT is enabled; this will allow you to access user/pass secured documents via http.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->load('http://news.google.com/?output=rss');
?>
RSS_PHP->loadRSS()
RSS_PHP->loadRSS(string $rss) - Load an RSS Document from a string into the RSS_PHP Object
deprecated this is included for backwards compatibility only, please use method loadXML()
RSS_PHP->loadXML()
RSS_PHP->loadXML(string $rss) - Load an XML Document from a string into the RSS_PHP Object
<?php
$LATIN1_Document = file_get_contents('http://rssphp.dev/verify/rss_1.0/rss.xml');
$RSS_PHP = new rss_php;
$RSS_PHP->loadXML($LATIN1_Document); #the document will automatically be converted to utf-8 on load
?>
RSS_PHP->loadArray()
RSS_PHP->loadArray(array $array, string $rootNodeName) - Load an array into the RSS_PHP Object
if $rootNodeName is specified then RSS_PHP will create a root node of the specified name and attach the array to it.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->loadArray($_SERVER, 'SERVER'); #load an array into a root node called SERVER
echo $RSS_PHP->getXML(); #return the array formatted as XML
?>
RSS_PHP->getRSS()
RSS_PHP->getRSS(bool $includeAttribues) - Return the complete RSS Document as an Array, if $includeAttribues is TRUE then attributes AND DOMElements are included.
deprecated included for backwards compatibility only, please use getValues()
RSS_PHP->getValues()
RSS_PHP->getValues(bool $includeAttribues) - Return the complete XML Document as an Array, if $includeAttribues is TRUE then attributes AND DOMElements are included.
note values are returned by reference, allowing you to change XML on the fly.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->load($url);
$rss_basic = $RSS_PHP->getValues(); #return the document property WITHOUT attributes
$rss_full = $RSS_PHP->getValues(true); #return the document property WITH attributes and DOMElements
?>
RSS_PHP->getItems()
RSS_PHP->getItems(bool $includeAttribues, int $limit, int $offset) - Return the RSS Document Items as an Array, if $includeAttribues is TRUE then attributes are included.
$limit and $offset allow you to return specific items, if ommited then all items are returned.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->load($url);
$top_items_basic = $RSS_PHP->getItems(false, 5); # return the top 5 items WITHOUT attributes
$items_full = $RSS_PHP->getItems(true); # all items WITH attributes
?>
RSS_PHP->query()
RSS_PHP->query(string $XPathQuery, bool $includeAttribues) - provides XPath query functionality to rss_php.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->load('http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml');
$channel_image_val = $RSS_PHP->query('channel/image'); #retrieve the values of the image node from channel
$item_thumbnails = $RSS_PHP->query('*/item/media:thumbnail', true)); #retrieve the media:thumbnail elements/array from all items (includes DOMElement, values and attributes)
?>
RSS_PHP->getElementsByTagName()
RSS_PHP->getElementsByTagName(string $tagName) - Return all elements with a node/tag name of $tagName.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->load('http://news.google.com/?output=rss');
$item_descriptions = $RSS_PHP->getElementsByTagName('description'); #return all item descriptions including DOMElements and attributes
?>
RSS_PHP->getValuesByTagName()
RSS_PHP->getValuesByTagName(string $tagName) - Return all element values with a node/tag name of $tagName.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->load('http://news.google.com/?output=rss');
$item_descriptions = $RSS_PHP->getValuesByTagName('description'); #return all item descriptions
?>
RSS_PHP->getNamespaces()
RSS_PHP->getNamespaces() - retrieve all namespaces (xlmns / extensions) defined in the current document.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->load('http://news.google.com/?output=rss');
$namespaces = $RSS_PHP->getNamespaces();
?>
RSS_PHP->getProcessingInstructions()
RSS_PHP->getProcessingInstructions() - retrieve all DOM Processing Instructions (such as style sheets) defined in the current document.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->load('http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml');
$processingInstructions = $RSS_PHP->getProcessingInstructions();
?>
RSS_PHP->getXML()
RSS_PHP->getXML() - Return the complete XML Document as XML.
In the example below we turn google news rss from html to plain text.
<?php
$RSS_PHP = new rss_php;
$RSS_PHP->load('http://news.google.com/?output=rss');
$items = $RSS_PHP->getItems();
foreach($items as $index => $item) {
$items[$index]['description'] = strip_tags($item['description']); #turn the description into plain text
}
echo $RSS_PHP->getXML(); #echo out the modified XML/RSS
?>
note any changes you have made to any elements will be reflected in the output XML.
RSS-PHP Note:
RSS_PHP reset's itself on every load() and loadRSS(); meaning it is completely re-usable.