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