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                 $prevTags = $dbr->selectField( 'tag_summary', 'ts_tags', $tsConds, __METHOD__ );
 150                 $prevTags = $prevTags ? $prevTags : '';
 151                 $prevTags = array_filter( explode( ',', $prevTags ) );
 152                 $newTags = array_unique( array_merge( $prevTags, $tags ) );
 153                 sort( $prevTags );
 154                 sort( $newTags );
 155
 156                 if ( $prevTags == $newTags ) {
 157                         // No change.
 158                         return false;
 159                 }
 160
 161                 $dbw = wfGetDB( DB_MASTER );
 162                 $dbw->replace(
 163                         'tag_summary',
 164                         array( 'ts_rev_id', 'ts_rc_id', 'ts_log_id' ),
 165                         array_filter( array_merge( $tsConds, array( 'ts_tags' => implode( ',', $newTags ) ) ) ),
 166                         __METHOD__
 167                 );
 168
 169                 // Insert the tags rows.
 170                 $tagsRows = array();
 171                 foreach ( $tags as $tag ) { // Filter so we don't insert NULLs as zero accidentally.
 172                         $tagsRows[] = array_filter(
 173                                 array(
 174                                         'ct_tag' => $tag,
 175                                         'ct_rc_id' => $rc_id,
 176                                         'ct_log_id' => $log_id,
 177                                         'ct_rev_id' => $rev_id,
 178                                         'ct_params' => $params
 179                                 )
 180                         );
 181                 }
 182
 183                 $dbw->insert( 'change_tag', $tagsRows, __METHOD__, array( 'IGNORE' ) );
 184
 185                 return true;
 186         }
 187
 188         /**
 189          * Applies all tags-related changes to a query.
 190          * Handles selecting tags, and filtering.
 191          * Needs $tables to be set up properly, so we can figure out which join conditions to use.
 192          *
 193          * @param string|array $tables Table names, see DatabaseBase::select
 194          * @param string|array $fields Fields used in query, see DatabaseBase::select
 195          * @param string|array $conds Conditions used in query, see DatabaseBase::select
 196          * @param array $join_conds Join conditions, see DatabaseBase::select
 197          * @param array $options Options, see Database::select
 198          * @param bool|string $filter_tag Tag to select on
 199          *
 200          * @throws MWException When unable to determine appropriate JOIN condition for tagging
 201          */
 202         public static function modifyDisplayQuery( &$tables, &$fields, &$conds,
 203                                                                                 &$join_conds, &$options, $filter_tag = false ) {
 204                 global $wgRequest, $wgUseTagFilter;
 205
 206                 if ( $filter_tag === false ) {
 207                         $filter_tag = $wgRequest->getVal( 'tagfilter' );
 208                 }
 209
 210                 // Figure out which conditions can be done.
 211                 if ( in_array( 'recentchanges', $tables ) ) {
 212                         $join_cond = 'ct_rc_id=rc_id';
 213                 } elseif ( in_array( 'logging', $tables ) ) {
 214                         $join_cond = 'ct_log_id=log_id';
 215                 } elseif ( in_array( 'revision', $tables ) ) {
 216                         $join_cond = 'ct_rev_id=rev_id';
 217                 } elseif ( in_array( 'archive', $tables ) ) {
 218                         $join_cond = 'ct_rev_id=ar_rev_id';
 219                 } else {
 220                         throw new MWException( 'Unable to determine appropriate JOIN condition for tagging.' );
 221                 }
 222
 223                 $fields['ts_tags'] = wfGetDB( DB_SLAVE )->buildGroupConcatField(
 224                         ',', 'change_tag', 'ct_tag', $join_cond
 225                 );
 226
 227                 if ( $wgUseTagFilter && $filter_tag ) {
 228                         // Somebody wants to filter on a tag.
 229                         // Add an INNER JOIN on change_tag
 230
 231                         $tables[] = 'change_tag';
 232                         $join_conds['change_tag'] = array( 'INNER JOIN', $join_cond );
 233                         $conds['ct_tag'] = $filter_tag;
 234                 }
 235         }
 236
 237         /**
 238          * Build a text box to select a change tag
 239          *
 240          * @param string $selected tag to select by default
 241          * @param bool $fullForm
 242          *        - if false, then it returns an array of (label, form).
 243          *        - if true, it returns an entire form around the selector.
 244          * @param Title $title Title object to send the form to.
 245          *        Used when, and only when $fullForm is true.
 246          * @return string|array
 247          *        - if $fullForm is false: Array with
 248          *        - if $fullForm is true: String, html fragment
 249          */
 250         public static function buildTagFilterSelector( $selected = '',
 251                 $fullForm = false, Title $title = null
 252         ) {
 253                 global $wgUseTagFilter;
 254
 255                 if ( !$wgUseTagFilter || !count( self::listDefinedTags() ) ) {
 256                         return $fullForm ? '' : array();
 257                 }
 258
 259                 $data = array(
 260                         Html::rawElement(
 261                                 'label',
 262                                 array( 'for' => 'tagfilter' ),
 263                                 wfMessage( 'tag-filter' )->parse()
 264                         ),
 265                         Xml::input(
 266                                 'tagfilter',
 267                                 20,
 268                                 $selected,
 269                                 array( 'class' => 'mw-tagfilter-input', 'id' => 'tagfilter' )
 270                         )
 271                 );
 272
 273                 if ( !$fullForm ) {
 274                         return $data;
 275                 }
 276
 277                 $html = implode( '&#160;', $data );
 278                 $html .= "\n" .
 279                         Xml::element(
 280                                 'input',
 281                                 array( 'type' => 'submit', 'value' => wfMessage( 'tag-filter-submit' )->text() )
 282                         );
 283                 $html .= "\n" . Html::hidden( 'title', $title->getPrefixedText() );
 284                 $html = Xml::tags(
 285                         'form',
 286                         array( 'action' => $title->getLocalURL(), 'class' => 'mw-tagfilter-form', 'method' => 'get' ),
 287                         $html
 288                 );
 289
 290                 return $html;
 291         }
 292
 293         /**
 294          * Basically lists defined tags which count even if they aren't applied to anything.
 295          * Tags on items in table 'change_tag' which are not (or no longer) in table 'valid_tag'
 296          * are not included.
 297          *
 298          * Tries memcached first.
 299          *
 300          * @return string[] Array of strings: tags
 301          */
 302         public static function listDefinedTags() {
 303                 // Caching...
 304                 global $wgMemc;
 305                 $key = wfMemcKey( 'valid-tags' );
 306                 $tags = $wgMemc->get( $key );
 307                 if ( $tags ) {
 308                         return $tags;
 309                 }
 310
 311                 $emptyTags = array();
 312
 313                 // Some DB stuff
 314                 $dbr = wfGetDB( DB_SLAVE );
 315                 $res = $dbr->select( 'valid_tag', 'vt_tag', array(), __METHOD__ );
 316                 foreach ( $res as $row ) {
 317                         $emptyTags[] = $row->vt_tag;
 318                 }
 319
 320                 wfRunHooks( 'ListDefinedTags', array( &$emptyTags ) );
 321
 322                 $emptyTags = array_filter( array_unique( $emptyTags ) );
 323
 324                 // Short-term caching.
 325                 $wgMemc->set( $key, $emptyTags, 300 );
 326                 return $emptyTags;
 327         }
 328
 329         /**
 330          * Returns a map of any tags used on the wiki to number of edits
 331          * tagged with them, ordered descending by the hitcount.
 332          *
 333          * @return array Array of string => int
 334          */
 335         public static function tagUsageStatistics() {
 336                 $out = array();
 337
 338                 $dbr = wfGetDB( DB_SLAVE );
 339                 $res = $dbr->select(
 340                         'change_tag',
 341                         array( 'ct_tag', 'hitcount' => 'count(*)' ),
 342                         array(),
 343                         __METHOD__,
 344                         array( 'GROUP BY' => 'ct_tag', 'ORDER BY' => 'hitcount DESC' )
 345                 );
 346
 347                 foreach ( $res as $row ) {
 348                         $out[$row->ct_tag] = $row->hitcount;
 349                 }
 350                 foreach ( self::listDefinedTags() as $tag ) {
 351                         if ( !isset( $out[$tag] ) ) {
 352                                 $out[$tag] = 0;
 353                         }
 354                 }
 355
 356                 return $out;
 357         }
 358 }