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