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