<?php
+/**
+ * Feed to Special:RecentChanges and Special:RecentChangesLiked
+ *
+ * @ingroup Feed
+ */
class ChangesFeed {
-
public $format, $type, $titleMsg, $descMsg;
+ /**
+ * Constructor
+ *
+ * @param $format String: feed's format (either 'rss' or 'atom')
+ * @param $type String: type of feed (for cache keys)
+ */
public function __construct( $format, $type ) {
$this->format = $format;
$this->type = $type;
}
+ /**
+ * Get a ChannelFeed subclass object to use
+ *
+ * @param $title String: feed's title
+ * @param $description String: feed's description
+ * @return ChannelFeed subclass or false on failure
+ */
public function getFeedObject( $title, $description ) {
global $wgSitename, $wgContLanguageCode, $wgFeedClasses, $wgTitle;
$feedTitle = "$wgSitename - {$title} [$wgContLanguageCode]";
$feedTitle, htmlspecialchars( $description ), $wgTitle->getFullUrl() );
}
+ /**
+ * Generates feed's content
+ *
+ * @param $feed ChannelFeed subclass object (generally the one returned by getFeedObject())
+ * @param $rows ResultWrapper object with rows in recentchanges table
+ * @param $limit Integer: number of rows in $rows (only used for the cache key)
+ * @param $hideminor Boolean: whether to hide minor edits (only used for the cache key)
+ * @param $lastmod Integer: timestamp of the last item in the recentchanges table (only used for the cache key)
+ * @param $target String: target's name; for Special:RecentChangesLinked (only used for the cache key)
+ * @param $namespace Integer: namespace id (only used for the cache key)
+ * @return null or true
+ */
public function execute( $feed, $rows, $limit=0, $hideminor=false, $lastmod=false, $target='', $namespace='' ) {
global $messageMemc, $wgFeedCacheTimeout;
global $wgSitename, $wgLang;
return true;
}
+ /**
+ * Save to feed result to $messageMemc
+ *
+ * @param $feed String: feed's content
+ * @param $timekey String: memcached key of the last modification
+ * @param $key String: memcached key of the content
+ */
public function saveToCache( $feed, $timekey, $key ) {
global $messageMemc;
$expire = 3600 * 24; # One day
$messageMemc->set( $timekey, wfTimestamp( TS_MW ), $expire );
}
+ /**
+ * Try to load the feed result from $messageMemc
+ *
+ * @param $lastmod Integer: timestamp of the last item in the recentchanges table
+ * @param $timekey String: memcached key of the last modification
+ * @param $key String: memcached key of the content
+ * @return feed's content on cache hit or false on cache miss
+ */
public function loadFromCache( $lastmod, $timekey, $key ) {
global $wgFeedCacheTimeout, $messageMemc;
$feedLastmod = $messageMemc->get( $timekey );
}
/**
- * Generate the feed items given a row from the database.
- * @param $rows Database resource with recentchanges rows
- * @param $feed Feed object
- */
+ * Generate the feed items given a row from the database.
+ * @param $rows DatabaseBase resource with recentchanges rows
+ * @param $feed Feed object
+ */
public static function generateFeed( $rows, &$feed ) {
wfProfileIn( __METHOD__ );
# http://www.gnu.org/copyleft/gpl.html
/**
+ * @defgroup Feed Feed
+ *
* Basic support for outputting syndication feeds in RSS, other formats.
* Contain a feed class as well as classes to build rss / atom ... feeds
* Available feeds are defined in Defines.php
+ *
+ * @file
*/
/**
* A base class for basic support for outputting syndication feeds in RSS and other formats.
+ *
+ * @ingroup Feed
*/
class FeedItem {
/**#@+
var $Author = '';
/**#@-*/
- /**#@+
- * @todo document
- * @param $Url URL uniquely designating the item.
+ /**
+ * Constructor
+ *
+ * @param $Title String: Item's title
+ * @param $Description String
+ * @param $Url String: URL uniquely designating the item.
+ * @param $Date String: Item's date
+ * @param $Author String: Author's user name
+ * @param $Comments String
*/
function __construct( $Title, $Description, $Url, $Date = '', $Author = '', $Comments = '' ) {
$this->Title = $Title;
$this->Comments = $Comments;
}
+ /**
+ * Encode $string so that it can be safely embedded in a XML document
+ *
+ * @param $string String: string to encode
+ * @return String
+ */
public function xmlEncode( $string ) {
$string = str_replace( "\r\n", "\n", $string );
$string = preg_replace( '/[\x00-\x08\x0b\x0c\x0e-\x1f]/', '', $string );
return htmlspecialchars( $string );
}
+ /**
+ * Get the title of this item; already xml-encoded
+ *
+ * @return String
+ */
public function getTitle() {
return $this->xmlEncode( $this->Title );
}
+ /**
+ * Get the URL of this item; already xml-encoded
+ *
+ * @return String
+ */
public function getUrl() {
return $this->xmlEncode( $this->Url );
}
+ /**
+ * Get the description of this item; already xml-encoded
+ *
+ * @return String
+ */
public function getDescription() {
return $this->xmlEncode( $this->Description );
}
+ /**
+ * Get the language of this item
+ *
+ * @return String
+ */
public function getLanguage() {
global $wgContLanguageCode;
return $wgContLanguageCode;
}
+ /**
+ * Get the title of this item
+ *
+ * @return String
+ */
public function getDate() {
return $this->Date;
}
+
+ /**
+ * Get the author of this item; already xml-encoded
+ *
+ * @return String
+ */
public function getAuthor() {
return $this->xmlEncode( $this->Author );
}
+
+ /**
+ * Get the comment of this item; already xml-encoded
+ *
+ * @return String
+ */
public function getComments() {
return $this->xmlEncode( $this->Comments );
}
/**
* Quickie hack... strip out wikilinks to more legible form from the comment.
+ *
+ * @param $text String: wikitext
+ * @return String
*/
public static function stripComment( $text ) {
return preg_replace( '/\[\[([^]]*\|)?([^]]+)\]\]/', '\2', $text );
/**
* @todo document (needs one-sentence top-level class description).
+ * @ingroup Feed
*/
class ChannelFeed extends FeedItem {
/**#@+
*
* This should be called from the outHeader() method,
* but can also be called separately.
- *
- * @public
*/
- function httpHeaders() {
+ public function httpHeaders() {
global $wgOut;
# We take over from $wgOut, excepting its cache header info
/**
* Generate a RSS feed
+ *
+ * @ingroup Feed
*/
class RSSFeed extends ChannelFeed {
/**
* Format a date given a timestamp
- * @param integer $ts Timestamp
- * @return string Date string
+ *
+ * @param $ts Integer: timestamp
+ * @return String: date string
*/
function formatTime( $ts ) {
return gmdate( 'D, d M Y H:i:s \G\M\T', wfTimestamp( TS_UNIX, $ts ) );
/**
* Output an RSS 2.0 item
- * @param FeedItem item to be output
+ * @param $item FeedItem: item to be output
*/
function outItem( $item ) {
?>
/**
* Generate an Atom feed
+ *
+ * @ingroup Feed
*/
class AtomFeed extends ChannelFeed {
/**
<?php
-// TODO: document
+/**
+ * Helper functions for feeds
+ *
+ * @ingroup Feed
+ */
class FeedUtils {
+ /**
+ * Check whether feed's cache should be cleared; for changes feeds
+ * If the feed should be purged; $timekey and $key will be removed from
+ * $messageMemc
+ *
+ * @param $timekey String: cache key of the timestamp of the last item
+ * @param $key String: cache key of feed's content
+ */
public static function checkPurge( $timekey, $key ) {
global $wgRequest, $wgUser, $messageMemc;
$purge = $wgRequest->getVal( 'action' ) === 'purge';
}
}
+ /**
+ * Check whether feeds can be used and that $type is a valid feed type
+ *
+ * @param $type String: feed type, as requested by the user
+ * @return Boolean
+ */
public static function checkFeedOutput( $type ) {
global $wgFeed, $wgFeedClasses;
}
/**
- * Format a diff for the newsfeed
- */
+ * Format a diff for the newsfeed
+ *
+ * @param $row Object: row from the recentchanges table
+ * @return String
+ */
public static function formatDiff( $row ) {
global $wgUser;
$actiontext );
}
+ /**
+ * Really format a diff for the newsfeed
+ *
+ * @param $title Title object
+ * @param $oldid Integer: old revision's id
+ * @param $newid Integer: new revision's id
+ * @param $timestamp Integer: new revision's timestamp
+ * @param $comment String: new revision's comment
+ * @param $actiontext String: text of the action; in case of log event
+ * @return String
+ */
public static function formatDiffRow( $title, $oldid, $newid, $timestamp, $comment, $actiontext='' ) {
global $wgFeedDiffCutoff, $wgContLang, $wgUser;
wfProfileIn( __FUNCTION__ );
}
/**
- * Hacky application of diff styles for the feeds.
- * Might be 'cleaner' to use DOM or XSLT or something,
- * but *gack* it's a pain in the ass.
- *
- * @param $text String:
- * @return string
- * @private
- */
+ * Hacky application of diff styles for the feeds.
+ * Might be 'cleaner' to use DOM or XSLT or something,
+ * but *gack* it's a pain in the ass.
+ *
+ * @param $text String: diff's HTML output
+ * @return String: modified HTML
+ * @private
+ */
public static function applyDiffStyle( $text ) {
$styles = array(
'diff' => 'background-color: white; color:black;',