Documentation

Feed
in package

SMF

implements ActionInterface Uses BackwardCompatibility

This class contains the code necessary to display XML feeds.

Outputs xml data representing recent information or a profile.

Can be passed subactions which decide what is output: 'recent' for recent posts, 'news' for news topics, 'members' for recently registered members, 'profile' for a member's profile. 'posts' for a member's posts. 'personal_messages' for a member's personal messages.

When displaying a member's profile or posts, the u parameter identifies which member. Defaults to the current user's id. To display a member's personal messages, the u parameter must match the id of the current user.

Outputs can be in RSS 0.92, RSS 2, Atom, RDF, or our own custom XML format. Default is RSS 2.

Accessed via ?action=.xml.

Does not use any templates, sub templates, or template layers.

Uses Stats, Profile, Post, and PersonalMessage language files.

Interfaces

ActionInterface: Interface for all action classes.

Constants

MIME_TYPES = ['rss' => 'application/rss+xml', 'rss2' => 'application/rss+xml', 'atom' => 'application/atom+xml', 'rdf' => 'application/rdf+xml', 'smf' => 'text/xml']: An array of MIME types for feed formats.
XML_NAMESPACES = ['rss' => [], 'rss2' => ['atom' => 'htt' . 'p:/' . '/ww' . 'w.w3.o' . 'rg/2005/Atom'], 'atom' => ['' => 'htt' . 'p:/' . '/ww' . 'w.w3.o' . 'rg/2005/Atom'], 'rdf' => ['' => 'htt' . 'p:/' . '/purl.o' . 'rg/rss/1.0/', 'rdf' => 'htt' . 'p:/' . '/ww' . 'w.w3.o' . 'rg/1999/02/22-rdf-syntax-ns#', 'dc' => 'htt' . 'p:/' . '/purl.o' . 'rg/dc/elements/1.1/'], 'smf' => ['smf' => 'htt' . 'p:/' . '/ww' . 'w.simple' . 'machines.o' . 'rg/xml/%1s']]: An array of sprintf() strings to define XML namespaces.

Properties

$ascending : bool
$boards : array<string|int, mixed>
$data : array<string|int, mixed>
$format : string
$limit : int
$member : int
$metadata : array<string|int, mixed>
$query_this_board : string
$start_after : int
$subaction : string
$subactions : array<string|int, mixed>
$xml : array<string|int, mixed>
$host : string
$obj : object
$optimize_msg : array<string|int, mixed>
$backcompat : array<string|int, mixed>

Methods

__construct() : mixed: Constructor.
build() : array<string|int, mixed>: Builds the XML from the data.
call() : void: Convenience method to load() and execute() an instance of the child class.
cdataParse() : string: Ensures supplied data is properly encapsulated in cdata xml tags
emit() : void: Emits the feed as an XML file.
execute() : void: Fetches the data based on the sub-action, builds the XML, and emits it.
exportStatic() : void: Provides a way to export a class's public static properties and methods to global namespace.
getData() : array<string|int, mixed>: Retrieve the correct type of data based on $this->subaction.
getXmlMembers() : array<string|int, mixed>: Retrieve the list of members from database.
getXmlNews() : array<string|int, mixed>: Get the latest topics information from a specific board, to display later.
getXmlPMs() : array<string|int, mixed>: Get a user's personal messages.
getXmlPosts() : array<string|int, mixed>: Get a user's posts.
getXmlProfile() : array<string|int, mixed>: Get the profile information for member into an array, which will be generated to match the xml_format.
getXmlRecent() : array<string|int, mixed>: Get the recent topics to display.
load() : object: Static wrapper for constructor.
checkEnabled() : void
dumpTags() : void: Populates Utils::$context['feed']['items'].
fixPossibleUrl() : string: Called from self::dumpTags to convert data to XML.
setFormat() : mixed
setlimit() : mixed
setMember() : mixed
setSubaction() : mixed

MIME_TYPES

An array of MIME types for feed formats.


    public
        mixed
    MIME_TYPES
    = ['rss' => 'application/rss+xml', 'rss2' => 'application/rss+xml', 'atom' => 'application/atom+xml', 'rdf' => 'application/rdf+xml', 'smf' => 'text/xml']

XML_NAMESPACES

An array of sprintf() strings to define XML namespaces.


    public
        mixed
    XML_NAMESPACES
    = ['rss' => [], 'rss2' => ['atom' => 'htt' . 'p:/' . '/ww' . 'w.w3.o' . 'rg/2005/Atom'], 'atom' => ['' => 'htt' . 'p:/' . '/ww' . 'w.w3.o' . 'rg/2005/Atom'], 'rdf' => ['' => 'htt' . 'p:/' . '/purl.o' . 'rg/rss/1.0/', 'rdf' => 'htt' . 'p:/' . '/ww' . 'w.w3.o' . 'rg/1999/02/22-rdf-syntax-ns#', 'dc' => 'htt' . 'p:/' . '/purl.o' . 'rg/dc/elements/1.1/'], 'smf' => ['smf' => 'htt' . 'p:/' . '/ww' . 'w.simple' . 'machines.o' . 'rg/xml/%1s']]

Do NOT change any of these to HTTPS addresses! Not even the SMF one.

Why? Because XML namespace names must be both unique and invariant once defined. They look like URLs merely because that's a convenient way to ensure uniqueness, but they are not used as URLs. They are used as case-sensitive identifier strings. If the string changes in any way, XML processing software (including PHP's own XML functions) will interpret the two versions of the string as entirely different namespaces, which could cause it to mangle the XML horrifically during processing.

These strings have been broken up and concatenated to help prevent any automatic search and replace attempts from changing them.

$ascending


    public
        bool
    $ascending
     = false

Whether data is in ascending order or not. Only relevant for some sub-actions.

$boards


    public
        array<string|int, mixed>
    $boards
     = []

Boards to fetch posts from.

$data


    public
        array<string|int, mixed>
    $data
     = []

Main data in this feed.

$format


    public
        string
    $format
     = 'rss2'

The requested feed format (e.g. RSS2, Atom, etc.)

$limit


    public
        int
    $limit
     = 5

Maximum number of items to fetch. Range: 1 - 255.

Only relevant for some sub-actions.

$member


    public
        int
    $member

ID of a member. Used by members, profile, posts, and personal_messages sub-actions.

$metadata


    public
        array<string|int, mixed>
    $metadata
     = []

Metadata about this feed.

$query_this_board


    public
        string
    $query_this_board
     = ''

Part of an SQL WHERE clause. Restricts query to only fetch posts from certain boards.

$start_after


    public
        int
    $start_after
     = 0

ID of item to start after. Only relevant for posts and personal_messages sub-actions.

$subaction


    public
        string
    $subaction
     = 'recent'

The requested sub-action.

$subactions


    public
    static    array<string|int, mixed>
    $subactions
     = ['recent' => 'getXmlRecent', 'news' => 'getXmlNews', 'members' => 'getXmlMembers', 'profile' => 'getXmlProfile', 'posts' => 'getXmlPosts', 'personal_messages' => 'getXmlPMs']

List all the different types of data they can pull.

$xml


    public
        array<string|int, mixed>
    $xml
     = ['header' => '', 'items' => '', 'footer' => '']

The constructed XML.

$host


    protected
        string
    $host
     = ''

Host extracted from $scripturl. Used to generate globally unique identifiers.

$obj


    protected
    static    object
    $obj

An instance of this class.

$optimize_msg


    protected
        array<string|int, mixed>
    $optimize_msg
     = ['highest' => 'm.id_msg <= b.id_last_msg', 'lowest' => 'm.id_msg >= 0']

Used to optimize SQL queries.

$backcompat


    private
    static    array<string|int, mixed>
    $backcompat
     = ['func_names' => ['call' => 'ShowXmlFeed', 'build' => 'buildXmlFeed', 'cdataParse' => 'cdata_parse']]

BackwardCompatibility settings for this class.

__construct()

Constructor.


    public
                    __construct([string $subaction = null ][, int $member = null ]) : mixed

Parameters

$subaction : string = null: Sets the sub-action to call. If null, will try $_GET['sa'] and then the default sub-action.
$member : int = null: The member whose data is being requested. If null, will try $_GET['u'] and then User::$me->id.

build()

Builds the XML from the data.


    public
            static        build(string $format, array<string|int, mixed> $data, array<string|int, mixed> $metadata, string $subaction) : array<string|int, mixed>

Returns an array containing three parts: the feed's header section, its items section, and its footer section. For convenience, the array is also made available as Utils::$context['feed'].

This method is static for the sake of the ExportProfileData task, which needs to do a lot of custom manipulation of the XML.

Parameters

$format : string: A supported feed format.
$data : array<string|int, mixed>: Structured data to build as XML.
$metadata : array<string|int, mixed>: Metadata about the feed.
$subaction : string: The sub-action that was requested.

Return values

array<string|int, mixed> —

The feed's header, items, and footer.

call()

Convenience method to load() and execute() an instance of the child class.


    public
            static        call() : void

cdataParse()

Ensures supplied data is properly encapsulated in cdata xml tags


    public
            static        cdataParse(string $data[, string $ns = '' ][, bool $force = false ]) : string

Parameters

$data : string: XML data
$ns : string = '': A namespace prefix for the XML data elements (used by mods, maybe)
$force : bool = false: If true, enclose the XML data in cdata tags no matter what (used by mods, maybe)

Return values

string —

The XML data enclosed in cdata tags when necessary

emit()

Emits the feed as an XML file.


    public
                    emit() : void

execute()

Fetches the data based on the sub-action, builds the XML, and emits it.


    public
                    execute() : void

exportStatic()

Provides a way to export a class's public static properties and methods to global namespace.


    public
            static        exportStatic() : void

To do so:

Use this trait in the class.
At the END of the class's file, call its exportStatic() method.

Although it might not seem that way at first glance, this approach conforms to section 2.3 of PSR 1, since executing this method is simply a dynamic means of declaring functions when the file is included; it has no other side effects.

Regarding the $backcompat items:

A class's static properties are not exported to global variables unless explicitly included in $backcompat['prop_names']. Likewise, a class's static methods are not exported as global functions unless explicitly included in $backcompat['func_names'].

$backcompat['prop_names'] is a simple array where the keys are the names of one or more of a class's static properties, and the values are the names of global variables. In each case, the global variable will be set to a reference to the static property. Static properties that are not named in this array will not be exported.

$backcompat['func_names'] is a simple array where the keys are the names of one or more of a class's static methods, and the values are the names that should be used for global functions that will encapsulate those methods. Methods that are not named in this array will not be exported.

Adding non-static properties or methods to the $backcompat arrays will produce runtime errors. It is the responsibility of the developer to make sure not to do this.

getData()

Retrieve the correct type of data based on $this->subaction.


    public
                    getData() : array<string|int, mixed>

The array will be structured to match $this->format.

Return values

array<string|int, mixed> —

An array of arrays of feed items. Each array has keys corresponding to the appropriate tags for the specified format.

getXmlMembers()

Retrieve the list of members from database.


    public
                    getXmlMembers() : array<string|int, mixed>

The array will be generated to match $this->format.

Return values

array<string|int, mixed> —

An array of arrays of feed items. Each array has keys corresponding to the appropriate tags for the specified format.

getXmlNews()

Get the latest topics information from a specific board, to display later.


    public
                    getXmlNews() : array<string|int, mixed>

The returned array will be generated to match the xml_format.

Return values

array<string|int, mixed> —

An array of arrays of topic data for the feed. Each array has keys corresponding to the tags for the specified format.

getXmlPMs()

Get a user's personal messages.


    public
                    getXmlPMs() : array<string|int, mixed>

Only the user can do this, and no one else -- not even the admin!

Return values

array<string|int, mixed> —

An array of arrays containing data for the feed. Each array has keys corresponding to the appropriate tags for the specified format.

getXmlPosts()

Get a user's posts.


    public
                    getXmlPosts() : array<string|int, mixed>

The returned array will be generated to match the xml_format.

Return values

array<string|int, mixed> —

An array of arrays containing data for the feed. Each array has keys corresponding to the appropriate tags for the specified format.

getXmlProfile()

Get the profile information for member into an array, which will be generated to match the xml_format.


    public
                    getXmlProfile() : array<string|int, mixed>

Return values

array<string|int, mixed> —

An array profile data

getXmlRecent()

Get the recent topics to display.


    public
                    getXmlRecent() : array<string|int, mixed>

The returned array will be generated to match the xml_format.

Return values

array<string|int, mixed> —

An array of arrays containing data for the feed. Each array has keys corresponding to the appropriate tags for the specified format.

load()

Static wrapper for constructor.


    public
            static        load() : object

Return values

object —

An instance of the class.

checkEnabled()


    protected
                    checkEnabled() : void

dumpTags()

Populates Utils::$context['feed']['items'].


    protected
            static        dumpTags(array<string|int, mixed> $data, int $i[, string $format = '' ][, array<string|int, mixed> $forceCdataKeys = [] ][, array<string|int, mixed> $nsKeys = [] ]) : void

Formats data retrieved in other functions into XML format. Additionally formats data based on the specific format passed. This function is recursively called to handle sub arrays of data.

Parameters

$data : array<string|int, mixed>: The array to output as XML data.
$i : int: The amount of indentation to use.
$format : string = '': The format to use ('atom', 'rss', 'rss2' or 'smf')
$forceCdataKeys : array<string|int, mixed> = []: A list of keys on which to force cdata wrapping (used by mods, maybe)
$nsKeys : array<string|int, mixed> = []: Key-value pairs of namespace prefixes to pass to self::cdataParse() (used by mods, maybe)

fixPossibleUrl()

Called from self::dumpTags to convert data to XML.


    protected
            static        fixPossibleUrl(string $val) : string

Finds URLs for local site and sanitizes them.

Parameters

$val : string: A string containing a possible URL.

Return values

string —

$val The string with any possible URLs sanitized.

setFormat()


    protected
                    setFormat() : mixed

setlimit()


    protected
                    setlimit() : mixed

setMember()


    protected
                    setMember(mixed $member) : mixed

Parameters

$member : mixed

setSubaction()


    protected
                    setSubaction(mixed $subaction) : mixed

Parameters

$subaction : mixed

Feed in package SMF implements ActionInterface Uses BackwardCompatibility

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

MIME_TYPES

XML_NAMESPACES

Properties

$ascending

$boards

$data

$format

$limit

$member

$metadata

$query_this_board

$start_after

$subaction

$subactions

$xml

$host

$obj

$optimize_msg

$backcompat

Methods

__construct()

Parameters

build()

Parameters

Return values

call()

cdataParse()

Parameters

Return values

emit()

execute()

exportStatic()

getData()

Return values

getXmlMembers()

Tags

Return values

getXmlNews()

Return values

getXmlPMs()

Return values

getXmlPosts()

Return values

getXmlProfile()

Return values

getXmlRecent()

Return values

load()

Return values

checkEnabled()

dumpTags()

Parameters

fixPossibleUrl()

Parameters

Return values

setFormat()

setlimit()

setMember()

Parameters

setSubaction()

Parameters

Feed
in package

SMF

implements ActionInterface Uses BackwardCompatibility