includes/ChangeTags.php

   1 <?php
   2 /**
   3  * Recent changes tagging.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 class ChangeTags {
  24         /**
  25          * Creates HTML for the given tags
  26          *
  27          * @param string $tags Comma-separated list of tags
  28          * @param string $page A label for the type of action which is being displayed,
  29          *   for example: 'history', 'contributions' or 'newpages'
  30          * @return array Array with two items: (html, classes)
  31          *   - html: String: HTML for displaying the tags (empty string when param $tags is empty)
  32          *   - classes: Array of strings: CSS classes used in the generated html, one class for each tag
  33          */
  34         public static function formatSummaryRow( $tags, $page ) {
  35                 global $wgLang;
  36
  37                 if ( !$tags ) {
  38                         return array( '', array() );
  39                 }
  40
  41                 $classes = array();
  42
  43                 $tags = explode( ',', $tags );
  44                 $displayTags = array();
  45                 foreach ( $tags as $tag ) {
  46                         $displayTags[] = Xml::tags(
  47                                 'span',
  48                                 array( 'class' => 'mw-tag-marker ' .
  49                                                                 Sanitizer::escapeClass( "mw-tag-marker-$tag" ) ),
  50                                 self::tagDescription( $tag )
  51                         );
  52                         $classes[] = Sanitizer::escapeClass( "mw-tag-$tag" );
  53                 }
  54                 $markers = wfMessage( 'tag-list-wrapper' )
  55                         ->numParams( count( $displayTags ) )
  56                         ->rawParams( $wgLang->commaList( $displayTags ) )
  57                         ->parse();
  58                 $markers = Xml::tags( 'span', array( 'class' => 'mw-tag-markers' ), $markers );
  59
  60                 return array( $markers, $classes );
  61         }
  62
  63         /**
  64          * Get a short description for a tag
  65          *
  66          * @param string $tag tag
  67          *
  68          * @return string Short description of the tag from "mediawiki:tag-$tag" if this message exists,
  69          *   html-escaped version of $tag otherwise
  70          */
  71         public static function tagDescription( $tag ) {
  72                 $msg = wfMessage( "tag-$tag" );
  73                 return $msg->exists() ? $msg->parse() : htmlspecialchars( $tag );
  74         }
  75
  76         /**
  77          * Add tags to a change given its rc_id, rev_id and/or log_id
  78          *
  79          * @param string|array $tags Tags to add to the change
  80          * @param int $rc_id rc_id of the change to add the tags to
  81          * @param int $rev_id rev_id of the change to add the tags to
  82          * @param int $log_id Log_id of the change to add the tags to
  83          * @param string $params params to put in the ct_params field of table 'change_tag'
  84          *
  85          * @throws MWException
  86          * @return bool false if no changes are made, otherwise true
  87          *
  88          * @exception MWException when $rc_id, $rev_id and $log_id are all null
  89          */
  90         public static function addTags( $tags, $rc_id = null, $rev_id = null,
  91                 $log_id = null, $params = null
  92         ) {
  93                 if ( !is_array( $tags ) ) {
  94                         $tags = array( $tags );
  95                 }
  96
  97                 $tags = array_filter( $tags ); // Make sure we're submitting all tags...
  98
  99                 if ( !$rc_id && !$rev_id && !$log_id ) {
 100                         throw new MWException( 'At least one of: RCID, revision ID, and log ID MUST be ' .
 101                                 'specified when adding a tag to a change!' );
 102                 }
 103
 104                 $dbr = wfGetDB( DB_SLAVE );
 105
 106                 // Might as well look for rcids and so on.
 107                 if ( !$rc_id ) {
 108                         // Info might be out of date, somewhat fractionally, on slave.
 109                         $dbr = wfGetDB( DB_MASTER );
 110                         if ( $log_id ) {
 111                                 $rc_id = $dbr->selectField(
 112                                         'recentchanges',
 113                                         'rc_id',
 114                                         array( 'rc_logid' => $log_id ),
 115                                         __METHOD__
 116                                 );
 117                         } elseif ( $rev_id ) {
 118                                 $rc_id = $dbr->selectField(
 119                                         'recentchanges',
 120                                         'rc_id',
 121                                         array( 'rc_this_oldid' => $rev_id ),
 122                                         __METHOD__
 123                                 );
 124                         }
 125                 } elseif ( !$log_id && !$rev_id ) {
 126                         // Info might be out of date, somewhat fractionally, on slave.
 127                         $dbr = wfGetDB( DB_MASTER );
 128                         $log_id = $dbr->selectField(
 129                                 'recentchanges',
 130                                 'rc_logid',
 131                                 array( 'rc_id' => $rc_id ),
 132                                 __METHOD__
 133                         );
 134                         $rev_id = $dbr->selectField(
 135                                 'recentchanges',
 136                                 'rc_this_oldid',
 137                                 array( 'rc_id' => $rc_id ),
 138                                 __METHOD__
 139                         );
 140                 }
 141
 142                 $tsConds = array_filter( array(
 143                         'ts_rc_id' => $rc_id,
 144                         'ts_rev_id' => $rev_id,
 145                         'ts_log_id' => $log_id )
 146                 );
 147
 148                 ## Update the summary row.
 149                 $dbw = wfGetDB( DB_MASTER );
 150                 // $prevTags can be out of date on slaves, especially when addTags is called consecutively,
 151                 // causing loss of tags added recently in tag_summary table.
 152                 $prevTags = $dbw->selectField( 'tag_summary', 'ts_tags', $tsConds, __METHOD__ );
 153                 $prevTags = $prevTags ? $prevTags : '';
 154                 $prevTags = array_filter( explode( ',', $prevTags ) );
 155                 $newTags = array_unique( array_merge( $prevTags, $tags ) );
 156                 sort( $prevTags );
 157                 sort( $newTags );
 158
 159                 if ( $prevTags == $newTags ) {
 160                         // No change.
 161                         return false;
 162                 }
 163
 164                 $dbw->replace(
 165                         'tag_summary',
 166                         array( 'ts_rev_id', 'ts_rc_id', 'ts_log_id' ),
 167                         array_filter( array_merge( $tsConds, array( 'ts_tags' => implode( ',', $newTags ) ) ) ),
 168                         __METHOD__
 169                 );
 170
 171                 // Insert the tags rows.
 172                 $tagsRows = array();
 173                 foreach ( $tags as $tag ) { // Filter so we don't insert NULLs as zero accidentally.
 174                         $tagsRows[] = array_filter(
 175                                 array(
 176                                         'ct_tag' => $tag,
 177                                         'ct_rc_id' => $rc_id,
 178                                         'ct_log_id' => $log_id,
 179                                         'ct_rev_id' => $rev_id,
 180                                         'ct_params' => $params
 181                                 )
 182                         );
 183                 }
 184
 185                 $dbw->insert( 'change_tag', $tagsRows, __METHOD__, array( 'IGNORE' ) );
 186
 187                 return true;
 188         }
 189
 190         /**
 191          * Applies all tags-related changes to a query.
 192          * Handles selecting tags, and filtering.
 193          * Needs $tables to be set up properly, so we can figure out which join conditions to use.
 194          *
 195          * @param string|array $tables Table names, see DatabaseBase::select
 196          * @param string|array $fields Fields used in query, see DatabaseBase::select
 197          * @param string|array $conds Conditions used in query, see DatabaseBase::select
 198          * @param array $join_conds Join conditions, see DatabaseBase::select
 199          * @param array $options Options, see Database::select
 200          * @param bool|string $filter_tag Tag to select on
 201          *
 202          * @throws MWException When unable to determine appropriate JOIN condition for tagging
 203          */
 204         public static function modifyDisplayQuery( &$tables, &$fields, &$conds,
 205                                                                                 &$join_conds, &$options, $filter_tag = false ) {
 206                 global $wgRequest, $wgUseTagFilter;
 207
 208                 if ( $filter_tag === false ) {
 209                         $filter_tag = $wgRequest->getVal( 'tagfilter' );
 210                 }
 211
 212                 // Figure out which conditions can be done.
 213                 if ( in_array( 'recentchanges', $tables ) ) {
 214                         $join_cond = 'ct_rc_id=rc_id';
 215                 } elseif ( in_array( 'logging', $tables ) ) {
 216                         $join_cond = 'ct_log_id=log_id';
 217                 } elseif ( in_array( 'revision', $tables ) ) {
 218                         $join_cond = 'ct_rev_id=rev_id';
 219                 } elseif ( in_array( 'archive', $tables ) ) {
 220                         $join_cond = 'ct_rev_id=ar_rev_id';
 221                 } else {
 222                         throw new MWException( 'Unable to determine appropriate JOIN condition for tagging.' );
 223                 }
 224
 225                 $fields['ts_tags'] = wfGetDB( DB_SLAVE )->buildGroupConcatField(
 226                         ',', 'change_tag', 'ct_tag', $join_cond
 227                 );
 228
 229                 if ( $wgUseTagFilter && $filter_tag ) {
 230                         // Somebody wants to filter on a tag.
 231                         // Add an INNER JOIN on change_tag
 232
 233                         $tables[] = 'change_tag';
 234                         $join_conds['change_tag'] = array( 'INNER JOIN', $join_cond );
 235                         $conds['ct_tag'] = $filter_tag;
 236                 }
 237         }
 238
 239         /**
 240          * Build a text box to select a change tag
 241          *
 242          * @param string $selected tag to select by default
 243          * @param bool $fullForm
 244          *        - if false, then it returns an array of (label, form).
 245          *        - if true, it returns an entire form around the selector.
 246          * @param Title $title Title object to send the form to.
 247          *        Used when, and only when $fullForm is true.
 248          * @return string|array
 249          *        - if $fullForm is false: Array with
 250          *        - if $fullForm is true: String, html fragment
 251          */
 252         public static function buildTagFilterSelector( $selected = '',
 253                 $fullForm = false, Title $title = null
 254         ) {
 255                 global $wgUseTagFilter;
 256
 257                 if ( !$wgUseTagFilter || !count( self::listDefinedTags() ) ) {
 258                         return $fullForm ? '' : array();
 259                 }
 260
 261                 $data = array(
 262                         Html::rawElement(
 263                                 'label',
 264                                 array( 'for' => 'tagfilter' ),
 265                                 wfMessage( 'tag-filter' )->parse()
 266                         ),
 267                         Xml::input(
 268                                 'tagfilter',
 269                                 20,
 270                                 $selected,
 271                                 array( 'class' => 'mw-tagfilter-input', 'id' => 'tagfilter' )
 272                         )
 273                 );
 274
 275                 if ( !$fullForm ) {
 276                         return $data;
 277                 }
 278
 279                 $html = implode( '&#160;', $data );
 280                 $html .= "\n" .
 281                         Xml::element(
 282                                 'input',
 283                                 array( 'type' => 'submit', 'value' => wfMessage( 'tag-filter-submit' )->text() )
 284                         );
 285                 $html .= "\n" . Html::hidden( 'title', $title->getPrefixedText() );
 286                 $html = Xml::tags(
 287                         'form',
 288                         array( 'action' => $title->getLocalURL(), 'class' => 'mw-tagfilter-form', 'method' => 'get' ),
 289                         $html
 290                 );
 291
 292                 return $html;
 293         }
 294
 295         /**
 296          * Basically lists defined tags which count even if they aren't applied to anything.
 297          * Tags on items in table 'change_tag' which are not (or no longer) in table 'valid_tag'
 298          * are not included.
 299          *
 300          * Tries memcached first.
 301          *
 302          * @return string[] Array of strings: tags
 303          */
 304         public static function listDefinedTags() {
 305                 // Caching...
 306                 global $wgMemc;
 307                 $key = wfMemcKey( 'valid-tags' );
 308                 $tags = $wgMemc->get( $key );
 309                 if ( $tags ) {
 310                         return $tags;
 311                 }
 312
 313                 $emptyTags = array();
 314
 315                 // Some DB stuff
 316                 $dbr = wfGetDB( DB_SLAVE );
 317                 $res = $dbr->select( 'valid_tag', 'vt_tag', array(), __METHOD__ );
 318                 foreach ( $res as $row ) {
 319                         $emptyTags[] = $row->vt_tag;
 320                 }
 321
 322                 wfRunHooks( 'ListDefinedTags', array( &$emptyTags ) );
 323
 324                 $emptyTags = array_filter( array_unique( $emptyTags ) );
 325
 326                 // Short-term caching.
 327                 $wgMemc->set( $key, $emptyTags, 300 );
 328                 return $emptyTags;
 329         }
 330
 331         /**
 332          * Returns a map of any tags used on the wiki to number of edits
 333          * tagged with them, ordered descending by the hitcount.
 334          *
 335          * @return array Array of string => int
 336          */
 337         public static function tagUsageStatistics() {
 338                 $out = array();
 339
 340                 $dbr = wfGetDB( DB_SLAVE );
 341                 $res = $dbr->select(
 342                         'change_tag',
 343                         array( 'ct_tag', 'hitcount' => 'count(*)' ),
 344                         array(),
 345                         __METHOD__,
 346                         array( 'GROUP BY' => 'ct_tag', 'ORDER BY' => 'hitcount DESC' )
 347                 );
 348
 349                 foreach ( $res as $row ) {
 350                         $out[$row->ct_tag] = $row->hitcount;
 351                 }
 352                 foreach ( self::listDefinedTags() as $tag ) {
 353                         if ( !isset( $out[$tag] ) ) {
 354                                 $out[$tag] = 0;
 355                         }
 356                 }
 357
 358                 return $out;
 359         }
 360 }