includes/changes/ChangesListFilterGroup.php

   1 <?php
   2 /**
   3  * Represents a filter group (used on ChangesListSpecialPage and descendants)
   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  * @license GPL 2+
  22  * @author Matthew Flaschen
  23  */
  24
  25 // TODO: Might want to make a super-class or trait to share behavior (especially re
  26 // conflicts) between ChangesListFilter and ChangesListFilterGroup.
  27 // What to call it.  FilterStructure?  That would also let me make
  28 // setUnidirectionalConflict protected.
  29
  30 use Wikimedia\Rdbms\IDatabase;
  31
  32 /**
  33  * Represents a filter group (used on ChangesListSpecialPage and descendants)
  34  *
  35  * @since 1.29
  36  */
  37 abstract class ChangesListFilterGroup {
  38         /**
  39          * Name (internal identifier)
  40          *
  41          * @var string $name
  42          */
  43         protected $name;
  44
  45         /**
  46          * i18n key for title
  47          *
  48          * @var string $title
  49          */
  50         protected $title;
  51
  52         /**
  53          * i18n key for header of What's This?
  54          *
  55          * @var string|null $whatsThisHeader
  56          */
  57         protected $whatsThisHeader;
  58
  59         /**
  60          * i18n key for body of What's This?
  61          *
  62          * @var string|null $whatsThisBody
  63          */
  64         protected $whatsThisBody;
  65
  66         /**
  67          * URL of What's This? link
  68          *
  69          * @var string|null $whatsThisUrl
  70          */
  71         protected $whatsThisUrl;
  72
  73         /**
  74          * i18n key for What's This? link
  75          *
  76          * @var string|null $whatsThisLinkText
  77          */
  78         protected $whatsThisLinkText;
  79
  80         /**
  81          * Type, from a TYPE constant of a subclass
  82          *
  83          * @var string $type
  84          */
  85         protected $type;
  86
  87         /**
  88          * Priority integer.  Higher values means higher up in the
  89          * group list.
  90          *
  91          * @var string $priority
  92          */
  93         protected $priority;
  94
  95         /**
  96          * Associative array of filters, as ChangesListFilter objects, with filter name as key
  97          *
  98          * @var array $filters
  99          */
 100         protected $filters;
 101
 102         /**
 103          * Whether this group is full coverage.  This means that checking every item in the
 104          * group means no changes list (e.g. RecentChanges) entries are filtered out.
 105          *
 106          * @var bool $isFullCoverage
 107          */
 108         protected $isFullCoverage;
 109
 110         /**
 111          * Array of associative arrays with conflict information.  See
 112          * setUnidirectionalConflict
 113          *
 114          * @var array $conflictingGroups
 115          */
 116         protected $conflictingGroups = [];
 117
 118         /**
 119          * Array of associative arrays with conflict information.  See
 120          * setUnidirectionalConflict
 121          *
 122          * @var array $conflictingFilters
 123          */
 124         protected $conflictingFilters = [];
 125
 126         const DEFAULT_PRIORITY = -100;
 127
 128         const RESERVED_NAME_CHAR = '_';
 129
 130         /**
 131          * Create a new filter group with the specified configuration
 132          *
 133          * @param array $groupDefinition Configuration of group
 134          * * $groupDefinition['name'] string Group name; use camelCase with no punctuation
 135          * * $groupDefinition['title'] string i18n key for title (optional, can be omitted
 136          *     only if none of the filters in the group display in the structured UI)
 137          * * $groupDefinition['type'] string A type constant from a subclass of this one
 138          * * $groupDefinition['priority'] int Priority integer.  Higher value means higher
 139          *     up in the group list (optional, defaults to -100).
 140          * * $groupDefinition['filters'] array Numeric array of filter definitions, each of which
 141          *     is an associative array to be passed to the filter constructor.  However,
 142          *     'priority' is optional for the filters.  Any filter that has priority unset
 143          *     will be put to the bottom, in the order given.
 144          * * $groupDefinition['isFullCoverage'] bool Whether the group is full coverage;
 145          *     if true, this means that checking every item in the group means no
 146          *     changes list entries are filtered out.
 147          * * $groupDefinition['whatsThisHeader'] string i18n key for header of "What's
 148          *     This" popup (optional).
 149          * * $groupDefinition['whatsThisBody'] string i18n key for body of "What's This"
 150          *     popup (optional).
 151          * * $groupDefinition['whatsThisUrl'] string URL for main link of "What's This"
 152          *     popup (optional).
 153          * * $groupDefinition['whatsThisLinkText'] string i18n key of text for main link of
 154          *     "What's This" popup (optional).
 155          */
 156         public function __construct( array $groupDefinition ) {
 157                 if ( strpos( $groupDefinition['name'], self::RESERVED_NAME_CHAR ) !== false ) {
 158                         throw new MWException( 'Group names may not contain \'' .
 159                                 self::RESERVED_NAME_CHAR .
 160                                 '\'.  Use the naming convention: \'camelCase\''
 161                         );
 162                 }
 163
 164                 $this->name = $groupDefinition['name'];
 165
 166                 if ( isset( $groupDefinition['title'] ) ) {
 167                         $this->title = $groupDefinition['title'];
 168                 }
 169
 170                 if ( isset( $groupDefinition['whatsThisHeader'] ) ) {
 171                         $this->whatsThisHeader = $groupDefinition['whatsThisHeader'];
 172                         $this->whatsThisBody = $groupDefinition['whatsThisBody'];
 173                         $this->whatsThisUrl = $groupDefinition['whatsThisUrl'];
 174                         $this->whatsThisLinkText = $groupDefinition['whatsThisLinkText'];
 175                 }
 176
 177                 $this->type = $groupDefinition['type'];
 178                 if ( isset( $groupDefinition['priority'] ) ) {
 179                         $this->priority = $groupDefinition['priority'];
 180                 } else {
 181                         $this->priority = self::DEFAULT_PRIORITY;
 182                 }
 183
 184                 $this->isFullCoverage = $groupDefinition['isFullCoverage'];
 185
 186                 $this->filters = [];
 187                 $lowestSpecifiedPriority = -1;
 188                 foreach ( $groupDefinition['filters'] as $filterDefinition ) {
 189                         if ( isset( $filterDefinition['priority'] ) ) {
 190                                 $lowestSpecifiedPriority = min( $lowestSpecifiedPriority, $filterDefinition['priority'] );
 191                         }
 192                 }
 193
 194                 // Convenience feature: If you specify a group (and its filters) all in
 195                 // one place, you don't have to specify priority.  You can just put them
 196                 // in order.  However, if you later add one (e.g. an extension adds a filter
 197                 // to a core-defined group), you need to specify it.
 198                 $autoFillPriority = $lowestSpecifiedPriority - 1;
 199                 foreach ( $groupDefinition['filters'] as $filterDefinition ) {
 200                         if ( !isset( $filterDefinition['priority'] ) ) {
 201                                 $filterDefinition['priority'] = $autoFillPriority;
 202                                 $autoFillPriority--;
 203                         }
 204                         $filterDefinition['group'] = $this;
 205
 206                         $filter = $this->createFilter( $filterDefinition );
 207                         $this->registerFilter( $filter );
 208                 }
 209         }
 210
 211         /**
 212          * Creates a filter of the appropriate type for this group, from the definition
 213          *
 214          * @param array $filterDefinition Filter definition
 215          * @return ChangesListFilter Filter
 216          */
 217         abstract protected function createFilter( array $filterDefinition );
 218
 219         /**
 220          * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with this object.
 221          *
 222          * WARNING: This means there is a conflict when both things are *shown*
 223          * (not filtered out), even for the hide-based filters.  So e.g. conflicting with
 224          * 'hideanons' means there is a conflict if only anonymous users are *shown*.
 225          *
 226          * @param ChangesListFilterGroup|ChangesListFilter $other Other
 227          *  ChangesListFilterGroup or ChangesListFilter
 228          * @param string $globalKey i18n key for top-level conflict message
 229          * @param string $forwardKey i18n key for conflict message in this
 230          *  direction (when in UI context of $this object)
 231          * @param string $backwardKey i18n key for conflict message in reverse
 232          *  direction (when in UI context of $other object)
 233          */
 234         public function conflictsWith( $other, $globalKey, $forwardKey, $backwardKey ) {
 235                 if ( $globalKey === null || $forwardKey === null || $backwardKey === null ) {
 236                         throw new MWException( 'All messages must be specified' );
 237                 }
 238
 239                 $this->setUnidirectionalConflict(
 240                         $other,
 241                         $globalKey,
 242                         $forwardKey
 243                 );
 244
 245                 $other->setUnidirectionalConflict(
 246                         $this,
 247                         $globalKey,
 248                         $backwardKey
 249                 );
 250         }
 251
 252         /**
 253          * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with
 254          * this object.
 255          *
 256          * Internal use ONLY.
 257          *
 258          * @param ChangesListFilterGroup|ChangesListFilter $other Other
 259          *  ChangesListFilterGroup or ChangesListFilter
 260          * @param string $globalDescription i18n key for top-level conflict message
 261          * @param string $contextDescription i18n key for conflict message in this
 262          *  direction (when in UI context of $this object)
 263          */
 264         public function setUnidirectionalConflict( $other, $globalDescription, $contextDescription ) {
 265                 if ( $other instanceof ChangesListFilterGroup ) {
 266                         $this->conflictingGroups[] = [
 267                                 'group' => $other->getName(),
 268                                 'groupObject' => $other,
 269                                 'globalDescription' => $globalDescription,
 270                                 'contextDescription' => $contextDescription,
 271                         ];
 272                 } elseif ( $other instanceof ChangesListFilter ) {
 273                         $this->conflictingFilters[] = [
 274                                 'group' => $other->getGroup()->getName(),
 275                                 'filter' => $other->getName(),
 276                                 'filterObject' => $other,
 277                                 'globalDescription' => $globalDescription,
 278                                 'contextDescription' => $contextDescription,
 279                         ];
 280                 } else {
 281                         throw new MWException( 'You can only pass in a ChangesListFilterGroup or a ChangesListFilter' );
 282                 }
 283         }
 284
 285         /**
 286          * @return string Internal name
 287          */
 288         public function getName() {
 289                 return $this->name;
 290         }
 291
 292         /**
 293          * @return string i18n key for title
 294          */
 295         public function getTitle() {
 296                 return $this->title;
 297         }
 298
 299         /**
 300          * @return string Type (TYPE constant from a subclass)
 301          */
 302         public function getType() {
 303                 return $this->type;
 304         }
 305
 306         /**
 307          * @return int Priority.  Higher means higher in the group list
 308          */
 309         public function getPriority() {
 310                 return $this->priority;
 311         }
 312
 313         /**
 314          * @return ChangesListFilter[] Associative array of ChangesListFilter objects, with
 315          *   filter name as key
 316          */
 317         public function getFilters() {
 318                 return $this->filters;
 319         }
 320
 321         /**
 322          * Get filter by name
 323          *
 324          * @param string $name Filter name
 325          * @return ChangesListFilter|null Specified filter, or null if it is not registered
 326          */
 327         public function getFilter( $name ) {
 328                 return isset( $this->filters[$name] ) ? $this->filters[$name] : null;
 329         }
 330
 331         /**
 332          * Gets the JS data in the format required by the front-end of the structured UI
 333          *
 334          * @return array|null Associative array, or null if there are no filters that
 335          *  display in the structured UI.  messageKeys is a special top-level value, with
 336          *  the value being an array of the message keys to send to the client.
 337          */
 338         public function getJsData() {
 339                 $output = [
 340                         'name' => $this->name,
 341                         'type' => $this->type,
 342                         'fullCoverage' => $this->isFullCoverage,
 343                         'filters' => [],
 344                         'priority' => $this->priority,
 345                         'conflicts' => [],
 346                         'messageKeys' => [ $this->title ]
 347                 ];
 348
 349                 if ( isset( $this->whatsThisHeader ) ) {
 350                         $output['whatsThisHeader'] = $this->whatsThisHeader;
 351                         $output['whatsThisBody'] = $this->whatsThisBody;
 352                         $output['whatsThisUrl'] = $this->whatsThisUrl;
 353                         $output['whatsThisLinkText'] = $this->whatsThisLinkText;
 354
 355                         array_push(
 356                                 $output['messageKeys'],
 357                                 $output['whatsThisHeader'],
 358                                 $output['whatsThisBody'],
 359                                 $output['whatsThisLinkText']
 360                         );
 361                 }
 362
 363                 usort( $this->filters, function ( $a, $b ) {
 364                         return $b->getPriority() - $a->getPriority();
 365                 } );
 366
 367                 foreach ( $this->filters as $filterName => $filter ) {
 368                         if ( $filter->displaysOnStructuredUi() ) {
 369                                 $filterData = $filter->getJsData();
 370                                 $output['messageKeys'] = array_merge(
 371                                         $output['messageKeys'],
 372                                         $filterData['messageKeys']
 373                                 );
 374                                 unset( $filterData['messageKeys'] );
 375                                 $output['filters'][] = $filterData;
 376                         }
 377                 }
 378
 379                 if ( count( $output['filters'] ) === 0 ) {
 380                         return null;
 381                 }
 382
 383                 $output['title'] = $this->title;
 384
 385                 $conflicts = array_merge(
 386                         $this->conflictingGroups,
 387                         $this->conflictingFilters
 388                 );
 389
 390                 foreach ( $conflicts as $conflictInfo ) {
 391                         unset( $conflictInfo['filterObject'] );
 392                         unset( $conflictInfo['groupObject'] );
 393                         $output['conflicts'][] = $conflictInfo;
 394                         array_push(
 395                                 $output['messageKeys'],
 396                                 $conflictInfo['globalDescription'],
 397                                 $conflictInfo['contextDescription']
 398                         );
 399                 }
 400
 401                 return $output;
 402         }
 403
 404         /**
 405          * Get groups conflicting with this filter group
 406          *
 407          * @return ChangesListFilterGroup[]
 408          */
 409         public function getConflictingGroups() {
 410                 return array_map(
 411                         function ( $conflictDesc ) {
 412                                 return $conflictDesc[ 'groupObject' ];
 413                         },
 414                         $this->conflictingGroups
 415                 );
 416         }
 417
 418         /**
 419          * Get filters conflicting with this filter group
 420          *
 421          * @return ChangesListFilter[]
 422          */
 423         public function getConflictingFilters() {
 424                 return array_map(
 425                         function ( $conflictDesc ) {
 426                                 return $conflictDesc[ 'filterObject' ];
 427                         },
 428                         $this->conflictingFilters
 429                 );
 430         }
 431
 432         /**
 433          * Check if any filter in this group is selected
 434          *
 435          * @param FormOptions $opts
 436          * @return bool
 437          */
 438         public function anySelected( FormOptions $opts ) {
 439                 return !!count( array_filter(
 440                         $this->getFilters(),
 441                         function ( ChangesListFilter $filter ) use ( $opts ) {
 442                                 return $filter->isSelected( $opts );
 443                         }
 444                 ) );
 445         }
 446
 447         /**
 448          * Modifies the query to include the filter group.
 449          *
 450          * The modification is only done if the filter group is in effect.  This means that
 451          * one or more valid and allowed filters were selected.
 452          *
 453          * @param IDatabase $dbr Database, for addQuotes, makeList, and similar
 454          * @param ChangesListSpecialPage $specialPage Current special page
 455          * @param array &$tables Array of tables; see IDatabase::select $table
 456          * @param array &$fields Array of fields; see IDatabase::select $vars
 457          * @param array &$conds Array of conditions; see IDatabase::select $conds
 458          * @param array &$query_options Array of query options; see IDatabase::select $options
 459          * @param array &$join_conds Array of join conditions; see IDatabase::select $join_conds
 460          * @param FormOptions $opts Wrapper for the current request options and their defaults
 461          * @param bool $isStructuredFiltersEnabled True if the Structured UI is currently enabled
 462          */
 463         abstract public function modifyQuery( IDatabase $dbr, ChangesListSpecialPage $specialPage,
 464                 &$tables, &$fields, &$conds, &$query_options, &$join_conds,
 465                 FormOptions $opts, $isStructuredFiltersEnabled );
 466
 467         /**
 468          * All the options represented by this filter group to $opts
 469          *
 470          * @param FormOptions $opts
 471          * @param bool $allowDefaults
 472          * @param bool $isStructuredFiltersEnabled
 473          */
 474         abstract public function addOptions( FormOptions $opts, $allowDefaults,
 475                 $isStructuredFiltersEnabled );
 476 }