2 /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
5 * Class representing feed-level data for an RSS2 feed
9 * LICENSE: This source file is subject to version 3.0 of the PHP license
10 * that is available through the world-wide-web at the following URI:
11 * http://www.php.net/license/3_0.txt. If you did not receive a copy of
12 * the PHP License and are unable to obtain it through the web, please
13 * send a note to license@php.net so we can mail you a copy immediately.
16 * @package XML_Feed_Parser
17 * @author James Stewart <james@jystewart.net>
18 * @copyright 2005 James Stewart <james@jystewart.net>
19 * @license http://www.gnu.org/copyleft/lesser.html GNU LGPL 2.1
20 * @version CVS: $Id: RSS2.php,v 1.12 2008/03/08 18:16:45 jystewart Exp $
21 * @link http://pear.php.net/package/XML_Feed_Parser/
25 * This class handles RSS2 feeds.
27 * @author James Stewart <james@jystewart.net>
28 * @version Release: 1.0.3
29 * @package XML_Feed_Parser
31 class XML_Feed_Parser_RSS2 extends XML_Feed_Parser_Type
34 * The URI of the RelaxNG schema used to (optionally) validate the feed
37 private $relax = 'rss20.rnc';
40 * We're likely to use XPath, so let's keep it global
46 * The feed type we are parsing
49 public $version = 'RSS 2.0';
52 * The class used to represent individual items
55 protected $itemClass = 'XML_Feed_Parser_RSS2Element';
58 * The element containing entries
61 protected $itemElement = 'item';
64 * Here we map those elements we're not going to handle individually
65 * to the constructs they are. The optional second parameter in the array
66 * tells the parser whether to 'fall back' (not apt. at the feed level) or
67 * fail if the element is missing. If the parameter is not set, the function
68 * will simply return false and leave it to the client to decide what to do.
71 protected $map = array(
72 'ttl' => array('Text'),
73 'pubDate' => array('Date'),
74 'lastBuildDate' => array('Date'),
75 'title' => array('Text'),
76 'link' => array('Link'),
77 'description' => array('Text'),
78 'language' => array('Text'),
79 'copyright' => array('Text'),
80 'managingEditor' => array('Text'),
81 'webMaster' => array('Text'),
82 'category' => array('Text'),
83 'generator' => array('Text'),
84 'docs' => array('Text'),
85 'ttl' => array('Text'),
86 'image' => array('Image'),
87 'skipDays' => array('skipDays'),
88 'skipHours' => array('skipHours'));
91 * Here we map some elements to their atom equivalents. This is going to be
92 * quite tricky to pull off effectively (and some users' methods may vary)
93 * but is worth trying. The key is the atom version, the value is RSS2.
96 protected $compatMap = array(
97 'title' => array('title'),
98 'rights' => array('copyright'),
99 'updated' => array('lastBuildDate'),
100 'subtitle' => array('description'),
101 'date' => array('pubDate'),
102 'author' => array('managingEditor'));
104 protected $namespaces = array(
105 'dc' => 'http://purl.org/rss/1.0/modules/dc/',
106 'content' => 'http://purl.org/rss/1.0/modules/content/');
109 * Our constructor does nothing more than its parent.
111 * @param DOMDocument $xml A DOM object representing the feed
112 * @param bool (optional) $string Whether or not to validate this feed
114 function __construct(DOMDocument $model, $strict = false)
116 $this->model = $model;
119 if (! $this->model->relaxNGValidate($this->relax)) {
120 throw new XML_Feed_Parser_Exception('Failed required validation');
124 $this->xpath = new DOMXPath($this->model);
125 foreach ($this->namespaces as $key => $value) {
126 $this->xpath->registerNamespace($key, $value);
128 $this->numberEntries = $this->count('item');
132 * Retrieves an entry by ID, if the ID is specified with the guid element
134 * This is not really something that will work with RSS2 as it does not have
135 * clear restrictions on the global uniqueness of IDs. But we can emulate
136 * it by allowing access based on the 'guid' element. If DOMXPath::evaluate
137 * is available, we also use that to store a reference to the entry in the array
138 * used by getEntryByOffset so that method does not have to seek out the entry
139 * if it's requested that way.
141 * @param string $id any valid ID.
142 * @return XML_Feed_Parser_RSS2Element
144 function getEntryById($id)
146 if (isset($this->idMappings[$id])) {
147 return $this->entries[$this->idMappings[$id]];
150 $entries = $this->xpath->query("//item[guid='$id']");
151 if ($entries->length > 0) {
152 $entry = new $this->itemElement($entries->item(0), $this);
153 if (in_array('evaluate', get_class_methods($this->xpath))) {
154 $offset = $this->xpath->evaluate("count(preceding-sibling::item)", $entries->item(0));
155 $this->entries[$offset] = $entry;
157 $this->idMappings[$id] = $entry;
163 * Get a category from the element
165 * The category element is a simple text construct which can occur any number
166 * of times. We allow access by offset or access to an array of results.
168 * @param string $call for compatibility with our overloading
169 * @param array $arguments - arg 0 is the offset, arg 1 is whether to return as array
170 * @return string|array|false
172 function getCategory($call, $arguments = array())
174 $categories = $this->model->getElementsByTagName('category');
175 $offset = empty($arguments[0]) ? 0 : $arguments[0];
176 $array = empty($arguments[1]) ? false : true;
177 if ($categories->length <= $offset) {
182 foreach ($categories as $category) {
183 array_push($list, $category->nodeValue);
187 return $categories->item($offset)->nodeValue;
191 * Get details of the image associated with the feed.
193 * @return array|false an array simply containing the child elements
195 protected function getImage()
197 $images = $this->xpath->query("//image");
198 if ($images->length > 0) {
199 $image = $images->item(0);
200 $desc = $image->getElementsByTagName('description');
201 $description = $desc->length ? $desc->item(0)->nodeValue : false;
202 $heigh = $image->getElementsByTagName('height');
203 $height = $heigh->length ? $heigh->item(0)->nodeValue : false;
204 $widt = $image->getElementsByTagName('width');
205 $width = $widt->length ? $widt->item(0)->nodeValue : false;
207 'title' => $image->getElementsByTagName('title')->item(0)->nodeValue,
208 'link' => $image->getElementsByTagName('link')->item(0)->nodeValue,
209 'url' => $image->getElementsByTagName('url')->item(0)->nodeValue,
210 'description' => $description,
218 * The textinput element is little used, but in the interests of
221 * @return array|false
223 function getTextInput()
225 $inputs = $this->model->getElementsByTagName('input');
226 if ($inputs->length > 0) {
227 $input = $inputs->item(0);
229 'title' => $input->getElementsByTagName('title')->item(0)->value,
231 $input->getElementsByTagName('description')->item(0)->value,
232 'name' => $input->getElementsByTagName('name')->item(0)->value,
233 'link' => $input->getElementsByTagName('link')->item(0)->value);
239 * Utility function for getSkipDays and getSkipHours
241 * This is a general function used by both getSkipDays and getSkipHours. It simply
242 * returns an array of the values of the children of the appropriate tag.
244 * @param string $tagName The tag name (getSkipDays or getSkipHours)
245 * @return array|false
247 protected function getSkips($tagName)
249 $hours = $this->model->getElementsByTagName($tagName);
250 if ($hours->length == 0) {
253 $skipHours = array();
254 foreach($hours->item(0)->childNodes as $hour) {
255 if ($hour instanceof DOMElement) {
256 array_push($skipHours, $hour->nodeValue);
263 * Retrieve skipHours data
265 * The skiphours element provides a list of hours on which this feed should
266 * not be checked. We return an array of those hours (integers, 24 hour clock)
270 function getSkipHours()
272 return $this->getSkips('skipHours');
276 * Retrieve skipDays data
278 * The skipdays element provides a list of days on which this feed should
279 * not be checked. We return an array of those days.
283 function getSkipDays()
285 return $this->getSkips('skipDays');
289 * Return content of the little-used 'cloud' element
291 * The cloud element is rarely used. It is designed to provide some details
292 * of a location to update the feed.
294 * @return array an array of the attributes of the element
298 $cloud = $this->model->getElementsByTagName('cloud');
299 if ($cloud->length == 0) {
302 $cloudData = array();
303 foreach ($cloud->item(0)->attributes as $attribute) {
304 $cloudData[$attribute->name] = $attribute->value;
312 * In RSS2 a link is a text element but in order to ensure that we resolve
313 * URLs properly we have a special function for them. We maintain the
314 * parameter used by the atom getLink method, though we only use the offset
317 * @param int $offset The position of the link within the feed. Starts from 0
318 * @param string $attribute The attribute of the link element required
319 * @param array $params An array of other parameters. Not used.
322 function getLink($offset, $attribute = 'href', $params = array())
324 $xPath = new DOMXPath($this->model);
325 $links = $xPath->query('//link');
327 if ($links->length <= $offset) {
330 $link = $links->item($offset);
331 return $this->addBase($link->nodeValue, $link);