| Index: trunk/phase3/includes/FeedUtils.php |
| — | — | @@ -1,8 +1,20 @@ |
| 2 | 2 | <?php |
| 3 | 3 | |
| 4 | | -// TODO: document |
| | 4 | +/** |
| | 5 | + * Helper functions for feeds |
| | 6 | + * |
| | 7 | + * @ingroup Feed |
| | 8 | + */ |
| 5 | 9 | class FeedUtils { |
| 6 | 10 | |
| | 11 | + /** |
| | 12 | + * Check whether feed's cache should be cleared; for changes feeds |
| | 13 | + * If the feed should be purged; $timekey and $key will be removed from |
| | 14 | + * $messageMemc |
| | 15 | + * |
| | 16 | + * @param $timekey String: cache key of the timestamp of the last item |
| | 17 | + * @param $key String: cache key of feed's content |
| | 18 | + */ |
| 7 | 19 | public static function checkPurge( $timekey, $key ) { |
| 8 | 20 | global $wgRequest, $wgUser, $messageMemc; |
| 9 | 21 | $purge = $wgRequest->getVal( 'action' ) === 'purge'; |
| — | — | @@ -12,6 +24,12 @@ |
| 13 | 25 | } |
| 14 | 26 | } |
| 15 | 27 | |
| | 28 | + /** |
| | 29 | + * Check whether feeds can be used and that $type is a valid feed type |
| | 30 | + * |
| | 31 | + * @param $type String: feed type, as requested by the user |
| | 32 | + * @return Boolean |
| | 33 | + */ |
| 16 | 34 | public static function checkFeedOutput( $type ) { |
| 17 | 35 | global $wgFeed, $wgFeedClasses; |
| 18 | 36 | |
| — | — | @@ -30,8 +48,11 @@ |
| 31 | 49 | } |
| 32 | 50 | |
| 33 | 51 | /** |
| 34 | | - * Format a diff for the newsfeed |
| 35 | | - */ |
| | 52 | + * Format a diff for the newsfeed |
| | 53 | + * |
| | 54 | + * @param $row Object: row from the recentchanges table |
| | 55 | + * @return String |
| | 56 | + */ |
| 36 | 57 | public static function formatDiff( $row ) { |
| 37 | 58 | global $wgUser; |
| 38 | 59 | |
| — | — | @@ -53,6 +74,17 @@ |
| 54 | 75 | $actiontext ); |
| 55 | 76 | } |
| 56 | 77 | |
| | 78 | + /** |
| | 79 | + * Really format a diff for the newsfeed |
| | 80 | + * |
| | 81 | + * @param $title Title object |
| | 82 | + * @param $oldid Integer: old revision's id |
| | 83 | + * @param $newid Integer: new revision's id |
| | 84 | + * @param $timestamp Integer: new revision's timestamp |
| | 85 | + * @param $comment String: new revision's comment |
| | 86 | + * @param $actiontext String: text of the action; in case of log event |
| | 87 | + * @return String |
| | 88 | + */ |
| 57 | 89 | public static function formatDiffRow( $title, $oldid, $newid, $timestamp, $comment, $actiontext='' ) { |
| 58 | 90 | global $wgFeedDiffCutoff, $wgContLang, $wgUser; |
| 59 | 91 | wfProfileIn( __FUNCTION__ ); |
| — | — | @@ -129,14 +161,14 @@ |
| 130 | 162 | } |
| 131 | 163 | |
| 132 | 164 | /** |
| 133 | | - * Hacky application of diff styles for the feeds. |
| 134 | | - * Might be 'cleaner' to use DOM or XSLT or something, |
| 135 | | - * but *gack* it's a pain in the ass. |
| 136 | | - * |
| 137 | | - * @param $text String: |
| 138 | | - * @return string |
| 139 | | - * @private |
| 140 | | - */ |
| | 165 | + * Hacky application of diff styles for the feeds. |
| | 166 | + * Might be 'cleaner' to use DOM or XSLT or something, |
| | 167 | + * but *gack* it's a pain in the ass. |
| | 168 | + * |
| | 169 | + * @param $text String: diff's HTML output |
| | 170 | + * @return String: modified HTML |
| | 171 | + * @private |
| | 172 | + */ |
| 141 | 173 | public static function applyDiffStyle( $text ) { |
| 142 | 174 | $styles = array( |
| 143 | 175 | 'diff' => 'background-color: white; color:black;', |
| Index: trunk/phase3/includes/Feed.php |
| — | — | @@ -19,13 +19,19 @@ |
| 20 | 20 | # http://www.gnu.org/copyleft/gpl.html |
| 21 | 21 | |
| 22 | 22 | /** |
| | 23 | + * @defgroup Feed Feed |
| | 24 | + * |
| 23 | 25 | * Basic support for outputting syndication feeds in RSS, other formats. |
| 24 | 26 | * Contain a feed class as well as classes to build rss / atom ... feeds |
| 25 | 27 | * Available feeds are defined in Defines.php |
| | 28 | + * |
| | 29 | + * @file |
| 26 | 30 | */ |
| 27 | 31 | |
| 28 | 32 | /** |
| 29 | 33 | * A base class for basic support for outputting syndication feeds in RSS and other formats. |
| | 34 | + * |
| | 35 | + * @ingroup Feed |
| 30 | 36 | */ |
| 31 | 37 | class FeedItem { |
| 32 | 38 | /**#@+ |
| — | — | @@ -39,9 +45,15 @@ |
| 40 | 46 | var $Author = ''; |
| 41 | 47 | /**#@-*/ |
| 42 | 48 | |
| 43 | | - /**#@+ |
| 44 | | - * @todo document |
| 45 | | - * @param $Url URL uniquely designating the item. |
| | 49 | + /** |
| | 50 | + * Constructor |
| | 51 | + * |
| | 52 | + * @param $Title String: Item's title |
| | 53 | + * @param $Description String |
| | 54 | + * @param $Url String: URL uniquely designating the item. |
| | 55 | + * @param $Date String: Item's date |
| | 56 | + * @param $Author String: Author's user name |
| | 57 | + * @param $Comments String |
| 46 | 58 | */ |
| 47 | 59 | function __construct( $Title, $Description, $Url, $Date = '', $Author = '', $Comments = '' ) { |
| 48 | 60 | $this->Title = $Title; |
| — | — | @@ -52,41 +64,87 @@ |
| 53 | 65 | $this->Comments = $Comments; |
| 54 | 66 | } |
| 55 | 67 | |
| | 68 | + /** |
| | 69 | + * Encode $string so that it can be safely embedded in a XML document |
| | 70 | + * |
| | 71 | + * @param $string String: string to encode |
| | 72 | + * @return String |
| | 73 | + */ |
| 56 | 74 | public function xmlEncode( $string ) { |
| 57 | 75 | $string = str_replace( "\r\n", "\n", $string ); |
| 58 | 76 | $string = preg_replace( '/[\x00-\x08\x0b\x0c\x0e-\x1f]/', '', $string ); |
| 59 | 77 | return htmlspecialchars( $string ); |
| 60 | 78 | } |
| 61 | 79 | |
| | 80 | + /** |
| | 81 | + * Get the title of this item; already xml-encoded |
| | 82 | + * |
| | 83 | + * @return String |
| | 84 | + */ |
| 62 | 85 | public function getTitle() { |
| 63 | 86 | return $this->xmlEncode( $this->Title ); |
| 64 | 87 | } |
| 65 | 88 | |
| | 89 | + /** |
| | 90 | + * Get the URL of this item; already xml-encoded |
| | 91 | + * |
| | 92 | + * @return String |
| | 93 | + */ |
| 66 | 94 | public function getUrl() { |
| 67 | 95 | return $this->xmlEncode( $this->Url ); |
| 68 | 96 | } |
| 69 | 97 | |
| | 98 | + /** |
| | 99 | + * Get the description of this item; already xml-encoded |
| | 100 | + * |
| | 101 | + * @return String |
| | 102 | + */ |
| 70 | 103 | public function getDescription() { |
| 71 | 104 | return $this->xmlEncode( $this->Description ); |
| 72 | 105 | } |
| 73 | 106 | |
| | 107 | + /** |
| | 108 | + * Get the language of this item |
| | 109 | + * |
| | 110 | + * @return String |
| | 111 | + */ |
| 74 | 112 | public function getLanguage() { |
| 75 | 113 | global $wgContLanguageCode; |
| 76 | 114 | return $wgContLanguageCode; |
| 77 | 115 | } |
| 78 | 116 | |
| | 117 | + /** |
| | 118 | + * Get the title of this item |
| | 119 | + * |
| | 120 | + * @return String |
| | 121 | + */ |
| 79 | 122 | public function getDate() { |
| 80 | 123 | return $this->Date; |
| 81 | 124 | } |
| | 125 | + |
| | 126 | + /** |
| | 127 | + * Get the author of this item; already xml-encoded |
| | 128 | + * |
| | 129 | + * @return String |
| | 130 | + */ |
| 82 | 131 | public function getAuthor() { |
| 83 | 132 | return $this->xmlEncode( $this->Author ); |
| 84 | 133 | } |
| | 134 | + |
| | 135 | + /** |
| | 136 | + * Get the comment of this item; already xml-encoded |
| | 137 | + * |
| | 138 | + * @return String |
| | 139 | + */ |
| 85 | 140 | public function getComments() { |
| 86 | 141 | return $this->xmlEncode( $this->Comments ); |
| 87 | 142 | } |
| 88 | 143 | |
| 89 | 144 | /** |
| 90 | 145 | * Quickie hack... strip out wikilinks to more legible form from the comment. |
| | 146 | + * |
| | 147 | + * @param $text String: wikitext |
| | 148 | + * @return String |
| 91 | 149 | */ |
| 92 | 150 | public static function stripComment( $text ) { |
| 93 | 151 | return preg_replace( '/\[\[([^]]*\|)?([^]]+)\]\]/', '\2', $text ); |
| — | — | @@ -96,6 +154,7 @@ |
| 97 | 155 | |
| 98 | 156 | /** |
| 99 | 157 | * @todo document (needs one-sentence top-level class description). |
| | 158 | + * @ingroup Feed |
| 100 | 159 | */ |
| 101 | 160 | class ChannelFeed extends FeedItem { |
| 102 | 161 | /**#@+ |
| — | — | @@ -133,10 +192,8 @@ |
| 134 | 193 | * |
| 135 | 194 | * This should be called from the outHeader() method, |
| 136 | 195 | * but can also be called separately. |
| 137 | | - * |
| 138 | | - * @public |
| 139 | 196 | */ |
| 140 | | - function httpHeaders() { |
| | 197 | + public function httpHeaders() { |
| 141 | 198 | global $wgOut; |
| 142 | 199 | |
| 143 | 200 | # We take over from $wgOut, excepting its cache header info |
| — | — | @@ -178,13 +235,16 @@ |
| 179 | 236 | |
| 180 | 237 | /** |
| 181 | 238 | * Generate a RSS feed |
| | 239 | + * |
| | 240 | + * @ingroup Feed |
| 182 | 241 | */ |
| 183 | 242 | class RSSFeed extends ChannelFeed { |
| 184 | 243 | |
| 185 | 244 | /** |
| 186 | 245 | * Format a date given a timestamp |
| 187 | | - * @param integer $ts Timestamp |
| 188 | | - * @return string Date string |
| | 246 | + * |
| | 247 | + * @param $ts Integer: timestamp |
| | 248 | + * @return String: date string |
| 189 | 249 | */ |
| 190 | 250 | function formatTime( $ts ) { |
| 191 | 251 | return gmdate( 'D, d M Y H:i:s \G\M\T', wfTimestamp( TS_UNIX, $ts ) ); |
| — | — | @@ -210,7 +270,7 @@ |
| 211 | 271 | |
| 212 | 272 | /** |
| 213 | 273 | * Output an RSS 2.0 item |
| 214 | | - * @param FeedItem item to be output |
| | 274 | + * @param $item FeedItem: item to be output |
| 215 | 275 | */ |
| 216 | 276 | function outItem( $item ) { |
| 217 | 277 | ?> |
| — | — | @@ -237,6 +297,8 @@ |
| 238 | 298 | |
| 239 | 299 | /** |
| 240 | 300 | * Generate an Atom feed |
| | 301 | + * |
| | 302 | + * @ingroup Feed |
| 241 | 303 | */ |
| 242 | 304 | class AtomFeed extends ChannelFeed { |
| 243 | 305 | /** |
| Index: trunk/phase3/includes/ChangesFeed.php |
| — | — | @@ -1,14 +1,31 @@ |
| 2 | 2 | <?php |
| 3 | 3 | |
| | 4 | +/** |
| | 5 | + * Feed to Special:RecentChanges and Special:RecentChangesLiked |
| | 6 | + * |
| | 7 | + * @ingroup Feed |
| | 8 | + */ |
| 4 | 9 | class ChangesFeed { |
| 5 | | - |
| 6 | 10 | public $format, $type, $titleMsg, $descMsg; |
| 7 | 11 | |
| | 12 | + /** |
| | 13 | + * Constructor |
| | 14 | + * |
| | 15 | + * @param $format String: feed's format (either 'rss' or 'atom') |
| | 16 | + * @param $type String: type of feed (for cache keys) |
| | 17 | + */ |
| 8 | 18 | public function __construct( $format, $type ) { |
| 9 | 19 | $this->format = $format; |
| 10 | 20 | $this->type = $type; |
| 11 | 21 | } |
| 12 | 22 | |
| | 23 | + /** |
| | 24 | + * Get a ChannelFeed subclass object to use |
| | 25 | + * |
| | 26 | + * @param $title String: feed's title |
| | 27 | + * @param $description String: feed's description |
| | 28 | + * @return ChannelFeed subclass or false on failure |
| | 29 | + */ |
| 13 | 30 | public function getFeedObject( $title, $description ) { |
| 14 | 31 | global $wgSitename, $wgContLanguageCode, $wgFeedClasses, $wgTitle; |
| 15 | 32 | $feedTitle = "$wgSitename - {$title} [$wgContLanguageCode]"; |
| — | — | @@ -18,6 +35,18 @@ |
| 19 | 36 | $feedTitle, htmlspecialchars( $description ), $wgTitle->getFullUrl() ); |
| 20 | 37 | } |
| 21 | 38 | |
| | 39 | + /** |
| | 40 | + * Generates feed's content |
| | 41 | + * |
| | 42 | + * @param $feed ChannelFeed subclass object (generally the one returned by getFeedObject()) |
| | 43 | + * @param $rows ResultWrapper object with rows in recentchanges table |
| | 44 | + * @param $limit Integer: number of rows in $rows (only used for the cache key) |
| | 45 | + * @param $hideminor Boolean: whether to hide minor edits (only used for the cache key) |
| | 46 | + * @param $lastmod Integer: timestamp of the last item in the recentchanges table (only used for the cache key) |
| | 47 | + * @param $target String: target's name; for Special:RecentChangesLinked (only used for the cache key) |
| | 48 | + * @param $namespace Integer: namespace id (only used for the cache key) |
| | 49 | + * @return null or true |
| | 50 | + */ |
| 22 | 51 | public function execute( $feed, $rows, $limit=0, $hideminor=false, $lastmod=false, $target='', $namespace='' ) { |
| 23 | 52 | global $messageMemc, $wgFeedCacheTimeout; |
| 24 | 53 | global $wgSitename, $wgLang; |
| — | — | @@ -52,6 +81,13 @@ |
| 53 | 82 | return true; |
| 54 | 83 | } |
| 55 | 84 | |
| | 85 | + /** |
| | 86 | + * Save to feed result to $messageMemc |
| | 87 | + * |
| | 88 | + * @param $feed String: feed's content |
| | 89 | + * @param $timekey String: memcached key of the last modification |
| | 90 | + * @param $key String: memcached key of the content |
| | 91 | + */ |
| 56 | 92 | public function saveToCache( $feed, $timekey, $key ) { |
| 57 | 93 | global $messageMemc; |
| 58 | 94 | $expire = 3600 * 24; # One day |
| — | — | @@ -59,6 +95,14 @@ |
| 60 | 96 | $messageMemc->set( $timekey, wfTimestamp( TS_MW ), $expire ); |
| 61 | 97 | } |
| 62 | 98 | |
| | 99 | + /** |
| | 100 | + * Try to load the feed result from $messageMemc |
| | 101 | + * |
| | 102 | + * @param $lastmod Integer: timestamp of the last item in the recentchanges table |
| | 103 | + * @param $timekey String: memcached key of the last modification |
| | 104 | + * @param $key String: memcached key of the content |
| | 105 | + * @return feed's content on cache hit or false on cache miss |
| | 106 | + */ |
| 63 | 107 | public function loadFromCache( $lastmod, $timekey, $key ) { |
| 64 | 108 | global $wgFeedCacheTimeout, $messageMemc; |
| 65 | 109 | $feedLastmod = $messageMemc->get( $timekey ); |
| — | — | @@ -86,10 +130,10 @@ |
| 87 | 131 | } |
| 88 | 132 | |
| 89 | 133 | /** |
| 90 | | - * Generate the feed items given a row from the database. |
| 91 | | - * @param $rows Database resource with recentchanges rows |
| 92 | | - * @param $feed Feed object |
| 93 | | - */ |
| | 134 | + * Generate the feed items given a row from the database. |
| | 135 | + * @param $rows DatabaseBase resource with recentchanges rows |
| | 136 | + * @param $feed Feed object |
| | 137 | + */ |
| 94 | 138 | public static function generateFeed( $rows, &$feed ) { |
| 95 | 139 | wfProfileIn( __METHOD__ ); |
| 96 | 140 | |