API Documentation
Back to top  

SimplePie

package SimplePie
subpackage API

 Methods

Magic method handler

__call(string $method, array $args) : mixed

Parameters

$method

string

Method name

$args

array

Arguments to the method

Returns

mixed

The SimplePie class contains feed level data and options

__construct() 

To use SimplePie, create the SimplePie object with no parameters. You can then set configuration options using the provided methods. After setting them, you must initialise the feed using $feed->init(). At that point the object's methods and properties will be available to you.

Previously, it was possible to pass in the feed URL along with cache options directly into the constructor. This has been removed as of 1.3 as it caused a lot of confusion.

since 1.0 Preview Release

Remove items that link back to this before destroying this object

__destruct() 

Used for converting object to a string

__toString() 

Enable/disable caching in SimplePie.

enable_cache(boolean $enable = true) 

This option allows you to disable caching all-together in SimplePie. However, disabling the cache can lead to longer load times.

since 1.0 Preview Release

Parameters

$enable

boolean

Enable caching

Set whether feed items should be sorted into reverse chronological order

enable_order_by_date(boolean $enable = true) 

Parameters

$enable

boolean

Sort as reverse chronological order.

encode_instead_of_strip() 

encode_instead_of_strip($enable = true) 

Parameters

$enable

Get the error message for the occurred error.

error() : string | array

Returns

stringarrayError message, or array of messages for multifeeds

Force the given data/URL to be treated as a feed

force_feed(boolean $enable = false) 

This tells SimplePie to ignore the content-type provided by the server. Be careful when using this option, as it will also disable autodiscovery.

since 1.1

Parameters

$enable

boolean

Force the given data/URL to be treated as a feed

Force SimplePie to use fsockopen() instead of cURL

force_fsockopen(boolean $enable = false) 
since 1.0 Beta 3

Parameters

$enable

boolean

Force fsockopen() to be used

get_all_discovered_feeds() 

get_all_discovered_feeds() 

Get an author for the feed

get_author(integer $key = 0) : \SimplePie_Author | null
since 1.1

Parameters

$key

integer

The author that you want to return. Remember that arrays begin with 0, not 1

Returns

\SimplePie_Authornull

Get all authors for the feed

get_authors() : array | null

Uses <atom:author>, <author>, <dc:creator> or <itunes:author>

since 1.1

Returns

arraynullList of {@see SimplePie_Author} objects

Get the base URL value from the feed

get_base(array $element = array()) : string

Uses <xml:base> if available, otherwise uses the first link in the feed, or failing that, the URL of the feed itself.

see
see

Parameters

$element

array

Returns

string

Get all categories for the feed

get_categories() : array | null

Uses <atom:category>, <category> or <dc:subject>

since Unknown

Returns

arraynullList of {@see SimplePie_Category} objects

Get a category for the feed

get_category(integer $key = 0) : \SimplePie_Category | null
since Unknown

Parameters

$key

integer

The category that you want to return. Remember that arrays begin with 0, not 1

Returns

\SimplePie_Categorynull

Get data for an channel-level element

get_channel_tags(string $namespace, string $tag) : array

This method allows you to get access to ANY element/attribute in the channel/header section of the feed.

See \SimplePie::get_feed_tags() for a description of the return value

since 1.0
see

Parameters

$namespace

string

The URL of the XML namespace of the elements you're trying to access

$tag

string

Tag name

Returns

array

Get a contributor for the feed

get_contributor(integer $key = 0) : \SimplePie_Author | null
since 1.1

Parameters

$key

integer

The contrbutor that you want to return. Remember that arrays begin with 0, not 1

Returns

\SimplePie_Authornull

Get all contributors for the feed

get_contributors() : array | null

Uses <atom:contributor>

since 1.1

Returns

arraynullList of {@see SimplePie_Author} objects

Get the copyright info for the feed

get_copyright() : string | null

Uses <atom:rights>, <atom:copyright> or <dc:rights>

since 1.0 (previously called `get_feed_copyright()` since 0.8)

Returns

stringnull

Get the content for the item

get_description() : string | null

Uses <atom:subtitle>, <atom:tagline>, <description>, <dc:description>, <itunes:summary> or <itunes:subtitle>

since 1.0 (previously called `get_feed_description()` since 0.8)

Returns

stringnull

Get the character encoding used for output

get_encoding() : string
since Preview Release

Returns

string

Get the favicon for the current feed

get_favicon() 
deprecated Use your own favicon handling instead

Get data for an feed-level element

get_feed_tags(string $namespace, string $tag) : array

This method allows you to get access to ANY element/attribute that is a sub-element of the opening feed tag.

The return value is an indexed array of elements matching the given namespace and tag name. Each element has attribs, data and child subkeys. For attribs and child, these contain namespace subkeys. attribs then has one level of associative name => value data (where value is a string) after the namespace. child has tag-indexed keys after the namespace, each member of which is an indexed array matching this same format.

For example:

// This is probably a bad example because we already support
//  natively, but it shows you how to parse through
// the nodes.
$group = $item->get_item_tags(SIMPLEPIE_NAMESPACE_MEDIARSS, 'group');
$content = $group[0]['child'][SIMPLEPIE_NAMESPACE_MEDIARSS]['content'];
$file = $content[0]['attribs']['']['url'];
echo $file;
since 1.0
see

Parameters

$namespace

string

The URL of the XML namespace of the elements you're trying to access

$tag

string

Tag name

Returns

array

Get the feed logo's height

get_image_height() : integer | float | null

RSS 2.0 feeds are allowed to have a "feed logo" height.

Uses <image><height> or defaults to 31.0 if no height is specified and the feed is an RSS 2.0 feed.

Returns

integerfloatnull

Get the feed logo's link

get_image_link() : string | null

RSS 0.9.0, 1.0 and 2.0 feeds are allowed to have a "feed logo" link. This points to a human-readable page that the image should link to.

Uses <itunes:image>, <atom:logo>, <atom:icon>, <image><title> or <image><dc:title>

Returns

stringnull

Get data for an channel-level element

get_image_tags(string $namespace, string $tag) : array

This method allows you to get access to ANY element/attribute in the image/logo section of the feed.

See \SimplePie::get_feed_tags() for a description of the return value

since 1.0
see

Parameters

$namespace

string

The URL of the XML namespace of the elements you're trying to access

$tag

string

Tag name

Returns

array

Get the feed logo's title

get_image_title() : string | null

RSS 0.9.0, 1.0 and 2.0 feeds are allowed to have a "feed logo" title.

Uses <image><title> or <image><dc:title>

Returns

stringnull

Get the feed logo's URL

get_image_url() : string | null

RSS 0.9.0, 2.0, Atom 1.0, and feeds with iTunes RSS tags are allowed to have a "feed logo" URL. This points directly to the image itself.

Uses <itunes:image>, <atom:logo>, <atom:icon>, <image><title> or <image><dc:title>

Returns

stringnull

Get the feed logo's link

get_image_width() : integer | float | null

RSS 2.0 feeds are allowed to have a "feed logo" width.

Uses <image><width> or defaults to 88.0 if no width is specified and the feed is an RSS 2.0 feed.

Returns

integerfloatnull

Get a single item from the feed

get_item(integer $key = 0) : \SimplePie_Item | null

This is better suited for for() loops, whereas \get_items() is better suited for foreach() loops.

see
since Beta 2

Parameters

$key

integer

The item that you want to return. Remember that arrays begin with 0, not 1

Returns

\SimplePie_Itemnull

Get the number of items in the feed

get_item_quantity(integer $max = 0) : integer

This is well-suited for for() loops with \get_item()

Parameters

$max

integer

Maximum value to return. 0 for no limit

Returns

integerNumber of items in the feed

Get all items from the feed

get_items(integer $start = 0, integer $end = 0) : array | null

This is better suited for for() loops, whereas \get_items() is better suited for foreach() loops.

see
since Beta 2

Parameters

$start

integer

Index to start at

$end

integer

Number of items to return. 0 for all items after $start

Returns

arraynullList of {@see SimplePie_Item} objects

Get the language for the feed

get_language() : string | null

Uses <language>, <dc:language>, or @xml_lang

since 1.0 (previously called `get_feed_language()` since 0.8)

Returns

stringnull

Get the latitude coordinates for the item

get_latitude() : string | null

Compatible with the W3C WGS84 Basic Geo and GeoRSS specifications

Uses <geo:lat> or <georss:point>

since 1.0
link W3C WGS84 Basic Geo
link GeoRSS

Returns

stringnull

Get a single link for the feed

get_link(integer $key = 0, string $rel = 'alternate') : string | null
since 1.0 (previously called `get_feed_link` since Preview Release, `get_feed_permalink()` since 0.8)

Parameters

$key

integer

The link that you want to return. Remember that arrays begin with 0, not 1

$rel

string

The relationship of the link to return

Returns

stringnullLink URL

Get all links for the feed

get_links(string $rel = 'alternate') : array | null

Uses <atom:link> or <link>

since Beta 2

Parameters

$rel

string

The relationship of links to return

Returns

arraynullLinks found for the feed (strings)

Get the longitude coordinates for the feed

get_longitude() : string | null

Compatible with the W3C WGS84 Basic Geo and GeoRSS specifications

Uses <geo:long>, <geo:lon> or <georss:point>

since 1.0
link W3C WGS84 Basic Geo
link GeoRSS

Returns

stringnull

Get the raw XML

get_raw_data() : string | boolean

This is the same as the old $feed->enable_xml_dump(true), but returns the data instead of printing it.

Returns

stringbooleanRaw XML data, false if the cache is used

Get the class registry

get_registry() : \SimplePie_Registry

Use this to override SimplePie's default classes

see

Returns

\SimplePie_Registry

Get the title of the feed

get_title() : string | null

Uses <atom:title>, <title> or <dc:title>

since 1.0 (previously called `get_feed_title` since 0.8)

Returns

stringnull

Get the type of the feed

get_type() : integer

This returns a SIMPLEPIETYPE* constant, which can be tested against using bitwise operators

since 0.8 (usage changed to using constants in 1.0)
see Unknown.
see RSS 0.90.
see RSS 0.91 (Netscape).
see RSS 0.91 (Userland).
see RSS 0.91.
see RSS 0.92.
see RSS 0.93.
see RSS 0.94.
see RSS 1.0.
see RSS 2.0.x.
see RDF-based RSS.
see Non-RDF-based RSS (truly intended as syndication format).
see Any version of RSS.
see Atom 0.3.
see Atom 1.0.
see Any version of Atom.
see Any known/supported feed type.

Returns

integerSIMPLEPIE_TYPE_* constant

Send the content-type header with correct encoding

handle_content_type(string $mime = 'text/html') 

This method ensures that the SimplePie-enabled page is being served with the correct mime-type and character encoding HTTP headers (character encoding determined by the \set_output_encoding config option).

This won't work properly if any content or whitespace has already been sent to the browser, because it relies on PHP's header() function, and these are the circumstances under which the function works.

Because it's setting these settings for the entire page (as is the nature of HTTP headers), this should only be used once per page (again, at the top).

Parameters

$mime

string

MIME type to serve the page as

Initialize the feed object

init() : boolean

This is what makes everything happen. Period. This is where all of the configuration options get processed, feeds are fetched, cached, and parsed, and all of that other good stuff.

Returns

booleanTrue if successful, false otherwise

Merge items from several feeds into one

merge_items(array $urls, integer $start = 0, integer $end = 0, integer $limit = 0) : array
Static

If you're merging multiple feeds together, they need to all have dates for the items or else SimplePie will refuse to sort them.

link http://simplepie.org/wiki/tutorial/sort_multiple_feeds_by_time_and_date#if_feeds_require_separate_per-feed_settings

Parameters

$urls

array

List of SimplePie feed objects to merge

$start

integer

Starting item

$end

integer

Number of items to return

$limit

integer

Maximum number of items per feed

Returns

array

remove_div() 

remove_div($enable = true) 

Parameters

$enable

Sanitize feed data

sanitize(string $data, integer $type, string $base = '') : string
access private
see

Parameters

$data

string

Data to sanitize

$type

integer

One of the SIMPLEPIECONSTRUCT* constants

$base

string

Base URL to resolve URLs against

Returns

stringSanitized data

Set which class SimplePie uses for handling author data

set_author_class($class = 'SimplePie_Author') 

Parameters

$class

Set the length of time (in seconds) that the autodiscovered feed URL will be cached

set_autodiscovery_cache_duration(integer $seconds = 604800) 

Parameters

$seconds

integer

The autodiscovered feed URL cache duration.

Set how much feed autodiscovery to do

set_autodiscovery_level(integer $level = SIMPLEPIE_LOCATOR_ALL) 
see
see
see
see
see
see
see

Parameters

$level

integer

Feed Autodiscovery Level (level can be a combination of the above constants, see bitwise OR operator)

Set which class SimplePie uses for caching

set_cache_class($class = 'SimplePie_Cache') 

Parameters

$class

Set the length of time (in seconds) that the contents of a feed will be cached

set_cache_duration(integer $seconds = 3600) 

Parameters

$seconds

integer

The feed content cache duration

Set the file system location where the cached files should be stored

set_cache_location(string $location = './cache') 

Parameters

$location

string

The file system location.

Set callback function to create cache filename with

set_cache_name_function(mixed $function = 'md5') 

Parameters

$function

mixed

Callback function

Set which class SimplePie uses for `<media:text>` captions

set_caption_class($class = 'SimplePie_Caption') 

Parameters

$class

Set which class SimplePie uses for handling category data

set_category_class($class = 'SimplePie_Category') 

Parameters

$class

Set which class SimplePie uses for content-type sniffing

set_content_type_sniffer_class($class = 'SimplePie_Content_Type_Sniffer') 

Parameters

$class

Set which class SimplePie uses for `<media:copyright>`

set_copyright_class($class = 'SimplePie_Copyright') 

Parameters

$class

Set which class SimplePie uses for `<media:credit>`

set_credit_class($class = 'SimplePie_Credit') 

Parameters

$class

Set which class SimplePie uses for feed enclosures

set_enclosure_class($class = 'SimplePie_Enclosure') 

Parameters

$class

Set the favicon handler

set_favicon_handler($page = false, $qs = 'i') 
deprecated Use your own favicon handling instead

Parameters

$page

$qs

Set the URL of the feed you want to parse

set_feed_url(string|array $url) 

This allows you to enter the URL of the feed you want to parse, or the website you want to try to use auto-discovery on. This takes priority over any set raw data.

You can set multiple feeds to mash together by passing an array instead of a string for the $url. Remember that with each additional feed comes additional processing and resources.

since 1.0 Preview Release
see

Parameters

$url

stringarray

This is the URL (or array of URLs) that you want to parse.

Set an instance of {@see SimplePie_File} to use as a feed

set_file(\SimplePie_File $file) : boolean

Parameters

$file

\SimplePie_File

&$file

Returns

booleanTrue on success, false on failure

Set which class SimplePie uses for remote file fetching

set_file_class($class = 'SimplePie_File') 

Parameters

$class

Set the handler to enable the display of cached images.

set_image_handler(\str $page = false, \str $qs = 'i') 

Parameters

$page

\str

Web-accessible path to the handler_image.php file.

$qs

\str

The query string that the value should be passed to.

Set the character encoding used to parse the feed

set_input_encoding(string $encoding = false) 

This overrides the encoding reported by the feed, however it will fall back to the normal encoding detection if the override fails

Parameters

$encoding

string

Character encoding

Set which class SimplePie uses for handling feed items

set_item_class($class = 'SimplePie_Item') 

Parameters

$class

Set the limit for items returned per-feed with multifeeds

set_item_limit(integer $limit = 0) 

Parameters

$limit

integer

The maximum number of items to return.

Set which class SimplePie uses for auto-discovery

set_locator_class($class = 'SimplePie_Locator') 

Parameters

$class

Set maximum number of feeds to check with autodiscovery

set_max_checked_feeds(integer $max = 10) 

Parameters

$max

integer

Maximum number of feeds to check

Set the output encoding

set_output_encoding(string $encoding = 'UTF-8') 

Allows you to override SimplePie's output to match that of your webpage. This is useful for times when your webpages are not being served as UTF-8. This setting will be obeyed by \handle_content_type(), and is similar to \set_input_encoding().

It should be noted, however, that not all character encodings can support all characters. If your page is being served as ISO-8859-1 and you try to display a Japanese feed, you'll likely see garbled characters. Because of this, it is highly recommended to ensure that your webpages are served as UTF-8.

The number of supported character encodings depends on whether your web host supports mbstring, iconv, or both. See http://simplepie.org/wiki/faq/Supported_Character_Encodings for more information.

Parameters

$encoding

string

Set which class SimplePie uses for XML parsing

set_parser_class($class = 'SimplePie_Parser') 

Parameters

$class

Set which class SimplePie uses for `<media:rating>`

set_rating_class($class = 'SimplePie_Rating') 

Parameters

$class

Set the raw XML data to parse

set_raw_data(string $data) 

Allows you to use a string of RSS/Atom data instead of a remote feed.

If you have a feed available as a string in PHP, you can tell SimplePie to parse that data string instead of a remote feed. Any set feed URL takes precedence.

since 1.0 Beta 3
see

Parameters

$data

string

RSS or Atom data as a string.

Set which class SimplePie uses for `<media:restriction>`

set_restriction_class($class = 'SimplePie_Restriction') 

Parameters

$class

Set which class SimplePie uses for data sanitization

set_sanitize_class($class = 'SimplePie_Sanitize') 

Parameters

$class

Set which class SimplePie uses item sources

set_source_class($class = 'SimplePie_Source') 

Parameters

$class

Set options to make SP as fast as possible

set_stupidly_fast(boolean $set = false) 

Forgoes a substantial amount of data sanitization in favor of speed. This turns SimplePie into a dumb parser of feeds.

Parameters

$set

boolean

Whether to set them or not

Set the the default timeout for fetching remote feeds

set_timeout(integer $timeout = 10) 

This allows you to change the maximum time the feed's server to respond and send the feed back.

since 1.0 Beta 3

Parameters

$timeout

integer

The maximum number of seconds to spend waiting to retrieve a feed.

Set element/attribute key/value pairs of HTML attributes containing URLs that need to be resolved relative to the feed

set_url_replacements(array|null $element_attribute = null) 

Defaults to |a|@href, |area|@href, |blockquote|@cite, |del|@cite, |form|@action, |img|@longdesc, |img|@src, |input|@src, |ins|@cite, |q|@cite

since 1.0

Parameters

$element_attribute

arraynull

Element/attribute key/value pairs, null for default

Set the user agent string

set_useragent(string $ua = SIMPLEPIE_USERAGENT) 

Parameters

$ua

string

New user agent string.

Sorting callback for items

sort_items(\SimplePie $a, \SimplePie $b) : boolean
Static
access private

Parameters

$a

\SimplePie

$b

\SimplePie

Returns

boolean

strip_attributes() 

strip_attributes($attribs = '') 

Parameters

$attribs

strip_comments() 

strip_comments($strip = false) 

Parameters

$strip

strip_htmltags() 

strip_htmltags($tags = '', $encode = null) 

Parameters

$tags

$encode

Get the URL for the feed

subscribe_url() : string | null

May or may not be different from the URL passed to \set_feed_url(), depending on whether auto-discovery was used.

since Preview Release (previously called `get_feed_url()` since SimplePie 0.8.)
todo If we have a perm redirect we should return the new URL
todo When we make the above change, let's support as well
todo Also, |atom:link|@rel=self

Returns

stringnull

Fetch the data via SimplePie_File

fetch_data(\SimplePie_Cache|false $cache) : array | true

If the data is already cached, attempt to fetch it from there instead

Parameters

$cache

\SimplePie_Cachefalse

Cache handler, or false to not load from the cache

Returns

arraytrueReturns true if the data was loaded from the cache, or an array of HTTP headers and sniffed type

 Properties

 

All the feeds found during the autodiscovery process

$all_discovered_feeds : array

Default

array()
see
access private
 

Feed Autodiscovery Level

$autodiscovery : integer

Default

SIMPLEPIE_LOCATOR_ALL
see
access private
 

Auto-discovery cache duration (in seconds)

$autodiscovery_cache_duration : integer

Default

604800
see
access private
 

Enable/Disable Caching

$cache : boolean

Default

true
see
access private
 

Cache duration (in seconds)

$cache_duration : integer

Default

3600
see
access private
 

Cache location (relative to executing script)

$cache_location : string

Default

'./cache'
see
access private
 

Function that creates the cache filename

$cache_name_function : string

Default

'md5'
see
access private
 

Stores the get_object_vars() array for use with multifeeds.

$config_settings : array

Default

null
see
access private
 

Raw data

$data : array

Default

array()
access private
 

Error string

$error : mixed

Default

access private
 

Feed URL

$feed_url : string

Default

see
access private
 

Instance of SimplePie_File to use as a feed

$file : object

Default

see
access private
 

Force the given data/URL to be treated as a feed no matter what it appears like

$force_feed : boolean

Default

false
see
access private
 

Forces fsockopen() to be used for remote files instead of cURL, even if a new enough version is installed

$force_fsockopen : boolean

Default

false
see
access private
 

Web-accessible path to the handler_image.php file.

$image_handler : string

Default

''
see
access private
 

Force input encoding to be set to the follow value (false, or anything type-cast to false, disables this feature)

$input_encoding : mixed

Default

false
see
access private
 

Stores the number of items to return per-feed with multifeeds.

$item_limit : integer

Default

0
see
access private
 

Maximum number of feeds to check with autodiscovery

$max_checked_feeds : integer

Default

10
see
access private
 

Stores SimplePie objects when multiple feeds initialized.

$multifeed_objects : array

Default

array()
access private
 

Stores the URLs when multiple feeds are being initialized.

$multifeed_url : array

Default

array()
see
access private
 

Reorder feed by date descending

$order_by_date : boolean

Default

true
see
access private
 

Raw feed data

$raw_data : string

Default

see
access private
 

Class registry object

$registry : \SimplePie_Registry

Default

 

Instance of SimplePie_Sanitize (or other class)

$sanitize : object

Default

see
access private
 

Stores the default attributes to be stripped by strip_attributes().

$strip_attributes : array

Default

array('bgsound', 'class', 'expr', 'id', 'style', 'onclick', 'onerror', 'onfinish', 'onmouseover', 'onmouseout', 'onfocus', 'onblur', 'lowsrc', 'dynsrc')
see
access private
 

Stores the default tags to be stripped by strip_htmltags().

$strip_htmltags : array

Default

array('base', 'blink', 'body', 'doctype', 'embed', 'font', 'form', 'frame', 'frameset', 'html', 'iframe', 'input', 'marquee', 'meta', 'noscript', 'object', 'param', 'script', 'style')
see
access private
 

Timeout for fetching remote files

$timeout : integer

Default

10
see
access private
 

SimplePie Useragent

$useragent : string

Default

SIMPLEPIE_USERAGENT
see
access private