Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
/lib/simplepie/src/ -> SimplePie.php (source)

[Source view]

SimplePie A PHP-Based RSS and Atom Feed Framework. Takes the hard work out of managing a complete RSS/Atom solution.

Author: Ryan Parman
Author: Sam Sneddon
Author: Ryan McCue
Copyright: 2004-2016 Ryan Parman, Sam Sneddon, Ryan McCue
License: http://www.opensource.org/licenses/bsd-license.php BSD License
File Size: 3228 lines (120 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

SimplePie:: (100 methods):
  __construct()
  __toString()
  __destruct()
  force_feed()
  set_feed_url()
  set_file()
  set_raw_data()
  set_timeout()
  set_curl_options()
  force_fsockopen()
  enable_cache()
  set_cache()
  force_cache_fallback()
  set_cache_duration()
  set_autodiscovery_cache_duration()
  set_cache_location()
  get_cache_filename()
  enable_order_by_date()
  set_input_encoding()
  set_autodiscovery_level()
  get_registry()
  set_cache_class()
  set_locator_class()
  set_parser_class()
  set_file_class()
  set_sanitize_class()
  set_item_class()
  set_author_class()
  set_category_class()
  set_enclosure_class()
  set_caption_class()
  set_copyright_class()
  set_credit_class()
  set_rating_class()
  set_restriction_class()
  set_content_type_sniffer_class()
  set_source_class()
  set_useragent()
  set_cache_namefilter()
  set_cache_name_function()
  set_stupidly_fast()
  set_max_checked_feeds()
  remove_div()
  strip_htmltags()
  encode_instead_of_strip()
  rename_attributes()
  strip_attributes()
  add_attributes()
  set_output_encoding()
  strip_comments()
  set_url_replacements()
  set_https_domains()
  set_image_handler()
  set_item_limit()
  enable_exceptions()
  init()
  fetch_data()
  error()
  status_code()
  get_raw_data()
  get_encoding()
  handle_content_type()
  get_type()
  subscribe_url()
  get_feed_tags()
  get_channel_tags()
  get_image_tags()
  get_base()
  sanitize()
  get_title()
  get_category()
  get_categories()
  get_author()
  get_authors()
  get_contributor()
  get_contributors()
  get_link()
  get_permalink()
  get_links()
  get_all_discovered_feeds()
  get_description()
  get_copyright()
  get_language()
  get_latitude()
  get_longitude()
  get_image_title()
  get_image_url()
  get_image_link()
  get_image_width()
  get_image_height()
  get_item_quantity()
  get_item()
  get_items()
  set_favicon_handler()
  get_favicon()
  __call()
  sort_items()
  merge_items()
  store_links()
  get_cache()


Class: SimplePie  - X-Ref

SimplePie

__construct()   X-Ref
The SimplePie class contains feed level data and options

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.


__toString()   X-Ref
Used for converting object to a string


__destruct()   X-Ref
Remove items that link back to this before destroying this object


force_feed($enable = false)   X-Ref
Force the given data/URL to be treated as a feed

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

param: bool $enable Force the given data/URL to be treated as a feed

set_feed_url($url)   X-Ref
Set the URL of the feed you want to parse

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.

param: string|array $url This is the URL (or array of URLs) that you want to parse.

set_file(&$file)   X-Ref
Set an instance of {@see \SimplePie\File} to use as a feed

param: \SimplePie\File &$file
return: bool True on success, false on failure

set_raw_data($data)   X-Ref
Set the raw XML data to parse

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.

param: string $data RSS or Atom data as a string.

set_timeout($timeout = 10)   X-Ref
Set the default timeout for fetching remote feeds

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

param: int $timeout The maximum number of seconds to spend waiting to retrieve a feed.

set_curl_options(array $curl_options = [])   X-Ref
Set custom curl options

This allows you to change default curl options

param: array $curl_options Curl options to add to default settings

force_fsockopen($enable = false)   X-Ref
Force SimplePie to use fsockopen() instead of cURL

param: bool $enable Force fsockopen() to be used

enable_cache($enable = true)   X-Ref
Enable/disable caching in SimplePie.

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

param: bool $enable Enable caching

set_cache(CacheInterface $cache)   X-Ref
Set a PSR-16 implementation as cache

param: CacheInterface $psr16cache The PSR-16 cache implementation
return: void

force_cache_fallback($enable = false)   X-Ref
SimplePie to continue to fall back to expired cache, if enabled, when
feed is unavailable.

This tells SimplePie to ignore any file errors and fall back to cache
instead. This only works if caching is enabled and cached content
still exists.

param: bool $enable Force use of cache on fail.

set_cache_duration($seconds = 3600)   X-Ref
Set the length of time (in seconds) that the contents of a feed will be
cached

param: int $seconds The feed content cache duration

set_autodiscovery_cache_duration($seconds = 604800)   X-Ref
Set the length of time (in seconds) that the autodiscovered feed URL will
be cached

param: int $seconds The autodiscovered feed URL cache duration.

set_cache_location($location = './cache')   X-Ref
Set the file system location where the cached files should be stored

param: string $location The file system location.

get_cache_filename($url)   X-Ref
Return the filename (i.e. hash, without path and without extension) of the file to cache a given URL.

param: string $url The URL of the feed to be cached.
return: string A filename (i.e. hash, without path and without extension).

enable_order_by_date($enable = true)   X-Ref
Set whether feed items should be sorted into reverse chronological order

param: bool $enable Sort as reverse chronological order.

set_input_encoding($encoding = false)   X-Ref
Set the character encoding used to parse the feed

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

param: string $encoding Character encoding

set_autodiscovery_level($level = self::LOCATOR_ALL)   X-Ref
Set how much feed autodiscovery to do

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

get_registry()   X-Ref
Get the class registry

Use this to override SimplePie's default classes
return: Registry

set_cache_class($class = Cache::class)   X-Ref
Set which class SimplePie uses for caching

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_locator_class($class = Locator::class)   X-Ref
Set which class SimplePie uses for auto-discovery

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_parser_class($class = Parser::class)   X-Ref
Set which class SimplePie uses for XML parsing

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_file_class($class = File::class)   X-Ref
Set which class SimplePie uses for remote file fetching

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_sanitize_class($class = Sanitize::class)   X-Ref
Set which class SimplePie uses for data sanitization

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_item_class($class = Item::class)   X-Ref
Set which class SimplePie uses for handling feed items

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_author_class($class = Author::class)   X-Ref
Set which class SimplePie uses for handling author data

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_category_class($class = Category::class)   X-Ref
Set which class SimplePie uses for handling category data

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_enclosure_class($class = Enclosure::class)   X-Ref
Set which class SimplePie uses for feed enclosures

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_caption_class($class = Caption::class)   X-Ref
Set which class SimplePie uses for `<media:text>` captions

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_copyright_class($class = Copyright::class)   X-Ref
Set which class SimplePie uses for `<media:copyright>`

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_credit_class($class = Credit::class)   X-Ref
Set which class SimplePie uses for `<media:credit>`

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_rating_class($class = Rating::class)   X-Ref
Set which class SimplePie uses for `<media:rating>`

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_restriction_class($class = Restriction::class)   X-Ref
Set which class SimplePie uses for `<media:restriction>`

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_content_type_sniffer_class($class = Sniffer::class)   X-Ref
Set which class SimplePie uses for content-type sniffing

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_source_class($class = Source::class)   X-Ref
Set which class SimplePie uses item sources

param: string $class Name of custom class
return: boolean True on success, false otherwise

set_useragent($ua = null)   X-Ref
Set the user agent string

param: string $ua New user agent string.

set_cache_namefilter(NameFilter $filter)   X-Ref
Set a namefilter to modify the cache filename with

param: NameFilter $filter
return: void

set_cache_name_function($function = 'md5')   X-Ref
Set callback function to create cache filename with

param: mixed $function Callback function

set_stupidly_fast($set = false)   X-Ref
Set options to make SP as fast as possible

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

param: bool $set Whether to set them or not

set_max_checked_feeds($max = 10)   X-Ref
Set maximum number of feeds to check with autodiscovery

param: int $max Maximum number of feeds to check

remove_div($enable = true)   X-Ref
No description

strip_htmltags($tags = '', $encode = null)   X-Ref
No description

encode_instead_of_strip($enable = true)   X-Ref
No description

rename_attributes($attribs = '')   X-Ref
No description

strip_attributes($attribs = '')   X-Ref
No description

add_attributes($attribs = '')   X-Ref
No description

set_output_encoding($encoding = 'UTF-8')   X-Ref
Set the output encoding

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 {@see handle_content_type()}, and
is similar to {@see 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 {@link http://php.net/mbstring mbstring},
{@link http://php.net/iconv iconv}, or both. See
{@link http://simplepie.org/wiki/faq/Supported_Character_Encodings} for
more information.

param: string $encoding

strip_comments($strip = false)   X-Ref
No description

set_url_replacements($element_attribute = null)   X-Ref
Set element/attribute key/value pairs of HTML attributes
containing URLs that need to be resolved relative to the feed

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

param: array|null $element_attribute Element/attribute key/value pairs, null for default

set_https_domains($domains = [])   X-Ref
Set the list of domains for which to force HTTPS.

param: array List of HTTPS domains. Example array('biz', 'example.com', 'example.org', 'www.example.net').

set_image_handler($page = false, $qs = 'i')   X-Ref
Set the handler to enable the display of cached images.

param: string $page Web-accessible path to the handler_image.php file.
param: string $qs The query string that the value should be passed to.

set_item_limit($limit = 0)   X-Ref
Set the limit for items returned per-feed with multifeeds

param: integer $limit The maximum number of items to return.

enable_exceptions($enable = true)   X-Ref
Enable throwing exceptions

param: boolean $enable Should we throw exceptions, or use the old-style error property?

init()   X-Ref
Initialize the feed object

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.

return: boolean True if successful, false otherwise

fetch_data(&$cache)   X-Ref
Fetch the data via \SimplePie\File

If the data is already cached, attempt to fetch it from there instead
param: Base|DataCache|false $cache Cache handler, or false to not load from the cache
return: array|true Returns true if the data was loaded from the cache, or an array of HTTP headers and sniffed type

error()   X-Ref
Get the error message for the occurred error

return: string|array Error message, or array of messages for multifeeds

status_code()   X-Ref
Get the last HTTP status code

return: int Status code

get_raw_data()   X-Ref
Get the raw XML

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

return: string|boolean Raw XML data, false if the cache is used

get_encoding()   X-Ref
Get the character encoding used for output

return: string

handle_content_type($mime = 'text/html')   X-Ref
Send the content-type header with correct encoding

This method ensures that the SimplePie-enabled page is being served with
the correct {@link http://www.iana.org/assignments/media-types/ mime-type}
and character encoding HTTP headers (character encoding determined by the
{@see 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
{@link http://php.net/header 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).

param: string $mime MIME type to serve the page as

get_type()   X-Ref
Get the type of the feed

This returns a \SimplePie\SimplePie::TYPE_* constant, which can be tested against
using {@link http://php.net/language.operators.bitwise bitwise operators}

return: int \SimplePie\SimplePie::TYPE_* constant

subscribe_url($permanent = false)   X-Ref
Get the URL for the feed

When the 'permanent' mode is enabled, returns the original feed URL,
except in the case of an `HTTP 301 Moved Permanently` status response,
in which case the location of the first redirection is returned.

When the 'permanent' mode is disabled (default),
may or may not be different from the URL passed to {@see set_feed_url()},
depending on whether auto-discovery was used, and whether there were
any redirects along the way.

param: bool $permanent Permanent mode to return only the original URL or the first redirection
return: string|null

get_feed_tags($namespace, $tag)   X-Ref
Get data for an feed-level element

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:
<pre>
// This is probably a bad example because we already support
// <media:content> natively, but it shows you how to parse through
// the nodes.
$group = $item->get_item_tags(\SimplePie\SimplePie::NAMESPACE_MEDIARSS, 'group');
$content = $group[0]['child'][\SimplePie\SimplePie::NAMESPACE_MEDIARSS]['content'];
$file = $content[0]['attribs']['']['url'];
echo $file;
</pre>

param: string $namespace The URL of the XML namespace of the elements you're trying to access
param: string $tag Tag name
return: array

get_channel_tags($namespace, $tag)   X-Ref
Get data for an channel-level element

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

See {@see SimplePie::get_feed_tags()} for a description of the return value

param: string $namespace The URL of the XML namespace of the elements you're trying to access
param: string $tag Tag name
return: array

get_image_tags($namespace, $tag)   X-Ref
Get data for an channel-level element

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

See {@see SimplePie::get_feed_tags()} for a description of the return value

param: string $namespace The URL of the XML namespace of the elements you're trying to access
param: string $tag Tag name
return: array

get_base($element = [])   X-Ref
Get the base URL value from the feed

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

param: array $element
return: string

sanitize($data, $type, $base = '')   X-Ref
Sanitize feed data

param: string $data Data to sanitize
param: int $type One of the \SimplePie\SimplePie::CONSTRUCT_* constants
param: string $base Base URL to resolve URLs against
return: string Sanitized data

get_title()   X-Ref
Get the title of the feed

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

return: string|null

get_category($key = 0)   X-Ref
Get a category for the feed

param: int $key The category that you want to return. Remember that arrays begin with 0, not 1
return: \SimplePie\Category|null

get_categories()   X-Ref
Get all categories for the feed

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

return: array|null List of {@see \SimplePie\Category} objects

get_author($key = 0)   X-Ref
Get an author for the feed

param: int $key The author that you want to return. Remember that arrays begin with 0, not 1
return: \SimplePie\Author|null

get_authors()   X-Ref
Get all authors for the feed

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

return: array|null List of {@see \SimplePie\Author} objects

get_contributor($key = 0)   X-Ref
Get a contributor for the feed

param: int $key The contrbutor that you want to return. Remember that arrays begin with 0, not 1
return: \SimplePie\Author|null

get_contributors()   X-Ref
Get all contributors for the feed

Uses `<atom:contributor>`

return: array|null List of {@see \SimplePie\Author} objects

get_link($key = 0, $rel = 'alternate')   X-Ref
Get a single link for the feed

param: int $key The link that you want to return. Remember that arrays begin with 0, not 1
param: string $rel The relationship of the link to return
return: string|null Link URL

get_permalink()   X-Ref
Get the permalink for the item

Returns the first link available with a relationship of "alternate".
Identical to {@see get_link()} with key 0

return: string|null Link URL

get_links($rel = 'alternate')   X-Ref
Get all links for the feed

Uses `<atom:link>` or `<link>`

param: string $rel The relationship of links to return
return: array|null Links found for the feed (strings)

get_all_discovered_feeds()   X-Ref
No description

get_description()   X-Ref
Get the content for the item

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

return: string|null

get_copyright()   X-Ref
Get the copyright info for the feed

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

return: string|null

get_language()   X-Ref
Get the language for the feed

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

return: string|null

get_latitude()   X-Ref
Get the latitude coordinates for the item

Compatible with the W3C WGS84 Basic Geo and GeoRSS specifications

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

return: string|null

get_longitude()   X-Ref
Get the longitude coordinates for the feed

Compatible with the W3C WGS84 Basic Geo and GeoRSS specifications

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

return: string|null

get_image_title()   X-Ref
Get the feed logo's title

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>`

return: string|null

get_image_url()   X-Ref
Get the feed logo's URL

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>`

return: string|null

get_image_link()   X-Ref
Get the feed logo's link

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>`

return: string|null

get_image_width()   X-Ref
Get the feed logo's link

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

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

return: int|null

get_image_height()   X-Ref
Get the feed logo's height

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

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

return: int|null

get_item_quantity($max = 0)   X-Ref
Get the number of items in the feed

This is well-suited for {@link http://php.net/for for()} loops with
{@see get_item()}

param: int $max Maximum value to return. 0 for no limit
return: int Number of items in the feed

get_item($key = 0)   X-Ref
Get a single item from the feed

This is better suited for {@link http://php.net/for for()} loops, whereas
{@see get_items()} is better suited for
{@link http://php.net/foreach foreach()} loops.

param: int $key The item that you want to return. Remember that arrays begin with 0, not 1
return: \SimplePie\Item|null

get_items($start = 0, $end = 0)   X-Ref
Get all items from the feed

This is better suited for {@link http://php.net/for for()} loops, whereas
{@see get_items()} is better suited for
{@link http://php.net/foreach foreach()} loops.

param: int $start Index to start at
param: int $end Number of items to return. 0 for all items after `$start`
return: \SimplePie\Item[]|null List of {@see \SimplePie\Item} objects

set_favicon_handler($page = false, $qs = 'i')   X-Ref
Set the favicon handler


get_favicon()   X-Ref
Get the favicon for the current feed


__call($method, $args)   X-Ref
Magic method handler

param: string $method Method name
param: array $args Arguments to the method
return: mixed

sort_items($a, $b)   X-Ref
Sorting callback for items

param: SimplePie $a
param: SimplePie $b
return: boolean

merge_items($urls, $start = 0, $end = 0, $limit = 0)   X-Ref
Merge items from several feeds into one

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

param: array $urls List of SimplePie feed objects to merge
param: int $start Starting item
param: int $end Number of items to return
param: int $limit Maximum number of items per feed
return: array

store_links(&$file, $hub, $self)   X-Ref
Store PubSubHubbub links as headers

There is no way to find PuSH links in the body of a microformats feed,
so they are added to the headers when found, to be used later by get_links.
param: \SimplePie\File $file
param: string $hub
param: string $self

get_cache($feed_url = '')   X-Ref
Get a DataCache

param: string $feed_url Only needed for BC, can be removed in SimplePie 2.0.0
return: DataCache