includes/changes/ChangesListFilter.php

   1 <?php
   2 /**
   3  * Represents a filter (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 /**
  26  * Represents a filter (used on ChangesListSpecialPage and descendants)
  27  *
  28  * @since 1.29
  29  */
  30 abstract class ChangesListFilter {
  31         /**
  32          * Filter name
  33          *
  34          * @var string $name
  35          */
  36         protected $name;
  37
  38         /**
  39          * CSS class suffix used for attribution, e.g. 'bot'.
  40          *
  41          * In this example, if bot actions are included in the result set, this CSS class
  42          * will then be included in all bot-flagged actions.
  43          *
  44          * @var string|null $cssClassSuffix
  45          */
  46         protected $cssClassSuffix;
  47
  48         /**
  49          * Callable that returns true if and only if a row is attributed to this filter
  50          *
  51          * @var callable $isRowApplicableCallable
  52          */
  53         protected $isRowApplicableCallable;
  54
  55         /**
  56          * Group.  ChangesListFilterGroup this belongs to
  57          *
  58          * @var ChangesListFilterGroup $group
  59          */
  60         protected $group;
  61
  62         /**
  63          * i18n key of label for structured UI
  64          *
  65          * @var string $label
  66          */
  67         protected $label;
  68
  69         /**
  70          * i18n key of description for structured UI
  71          *
  72          * @var string $description
  73          */
  74         protected $description;
  75
  76         /**
  77          * Callable used to check whether this filter is allowed to take effect
  78          *
  79          * @var callable $isAllowedCallable
  80          */
  81         protected $isAllowedCallable;
  82
  83         /**
  84          * List of conflicting groups
  85          *
  86          * @var array $conflictingGroups Array of associative arrays with conflict
  87          *   information.  See setUnidirectionalConflict
  88          */
  89         protected $conflictingGroups = [];
  90
  91         /**
  92          * List of conflicting filters
  93          *
  94          * @var array $conflictingFilters Array of associative arrays with conflict
  95          *   information.  See setUnidirectionalConflict
  96          */
  97         protected $conflictingFilters = [];
  98
  99         /**
 100          * List of filters that are a subset of the current filter
 101          *
 102          * @var array $subsetFilters Array of associative arrays with subset information
 103          */
 104         protected $subsetFilters = [];
 105
 106         /**
 107          * Priority integer.  Higher value means higher up in the group's filter list.
 108          *
 109          * @var string $priority
 110          */
 111         protected $priority;
 112
 113         /**
 114          * Create a new filter with the specified configuration.
 115          *
 116          * It infers which UI (it can be either or both) to display the filter on based on
 117          * which messages are provided.
 118          *
 119          * If 'label' is provided, it will be displayed on the structured UI.  Thus,
 120          * 'label', 'description', and sub-class parameters are optional depending on which
 121          * UI it's for.
 122          *
 123          * @param array $filterDefinition ChangesListFilter definition
 124          *
 125          * $filterDefinition['name'] string Name of filter
 126          * $filterDefinition['cssClassSuffix'] string CSS class suffix, used to mark
 127          *  that a particular row belongs to this filter (when a row is included by the
 128          *  filter) (optional)
 129          * $filterDefinition['isRowApplicableCallable'] Callable taking two parameters, the
 130          *  IContextSource, and the RecentChange object for the row, and returning true if
 131          *  the row is attributed to this filter.  The above CSS class will then be
 132          *  automatically added (optional, required if cssClassSuffix is used).
 133          * $filterDefinition['group'] ChangesListFilterGroup Group.  Filter group this
 134          *  belongs to.
 135          * $filterDefinition['label'] string i18n key of label for structured UI.
 136          * $filterDefinition['description'] string i18n key of description for structured
 137          *  UI.
 138          * $filterDefinition['isAllowedCallable'] callable Callable taking two parameters,
 139          *  the class name of the special page and an IContextSource, and returning true
 140          *  if and only if the current user is permitted to use this filter on the current
 141          *  wiki.  If it returns false, it will both hide the UI (in all UIs) and prevent
 142          *  the DB query modification from taking effect. (optional, defaults to allowed)
 143          * $filterDefinition['priority'] int Priority integer.  Higher value means higher
 144          *  up in the group's filter list.
 145          */
 146         public function __construct( array $filterDefinition ) {
 147                 if ( isset( $filterDefinition['group'] ) ) {
 148                         $this->group = $filterDefinition['group'];
 149                 } else {
 150                         throw new MWException( 'You must use \'group\' to specify the ' .
 151                                 'ChangesListFilterGroup this filter belongs to' );
 152                 }
 153
 154                 $this->name = $filterDefinition['name'];
 155
 156                 if ( isset( $filterDefinition['cssClassSuffix'] ) ) {
 157                         $this->cssClassSuffix = $filterDefinition['cssClassSuffix'];
 158                         $this->isRowApplicableCallable = $filterDefinition['isRowApplicableCallable'];
 159                 }
 160
 161                 if ( isset( $filterDefinition['label'] ) ) {
 162                         $this->label = $filterDefinition['label'];
 163                         $this->description = $filterDefinition['description'];
 164                 }
 165
 166                 if ( isset( $filterDefinition['isAllowedCallable'] ) ) {
 167                         $this->isAllowedCallable = $filterDefinition['isAllowedCallable'];
 168                 }
 169
 170                 $this->priority = $filterDefinition['priority'];
 171
 172                 $this->group->registerFilter( $this );
 173         }
 174
 175         /**
 176          * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with this object.
 177          *
 178          * WARNING: This means there is a conflict when both things are *shown*
 179          * (not filtered out), even for the hide-based filters.  So e.g. conflicting with
 180          * 'hideanons' means there is a conflict if only anonymous users are *shown*.
 181          *
 182          * @param ChangesListFilterGroup|ChangesListFilter $other Other
 183          *  ChangesListFilterGroup or ChangesListFilter
 184          * @param string $globalKey i18n key for top-level conflict message
 185          * @param string $forwardKey i18n key for conflict message in this
 186          *  direction (when in UI context of $this object)
 187          * @param string $backwardKey i18n key for conflict message in reverse
 188          *  direction (when in UI context of $other object)
 189          */
 190         public function conflictsWith( $other, $globalKey, $forwardKey,
 191                 $backwardKey ) {
 192
 193                 if ( $globalKey === null || $forwardKey === null ||
 194                         $backwardKey === null ) {
 195
 196                         throw new MWException( 'All messages must be specified' );
 197                 }
 198
 199                 $this->setUnidirectionalConflict(
 200                         $other,
 201                         $globalKey,
 202                         $forwardKey
 203                 );
 204
 205                 $other->setUnidirectionalConflict(
 206                         $this,
 207                         $globalKey,
 208                         $backwardKey
 209                 );
 210         }
 211
 212         /**
 213          * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with
 214          * this object.
 215          *
 216          * Internal use ONLY.
 217          *
 218          * @param ChangesListFilterGroup|ChangesListFilter $other Other
 219          *  ChangesListFilterGroup or ChangesListFilter
 220          * @param string $globalDescription i18n key for top-level conflict message
 221          * @param string $contextDescription i18n key for conflict message in this
 222          *  direction (when in UI context of $this object)
 223          */
 224         public function setUnidirectionalConflict( $other, $globalDescription,
 225                 $contextDescription ) {
 226
 227                 if ( $other instanceof ChangesListFilterGroup ) {
 228                         $this->conflictingGroups[] = [
 229                                 'group' => $other->getName(),
 230                                 'globalDescription' => $globalDescription,
 231                                 'contextDescription' => $contextDescription,
 232                         ];
 233                 } elseif ( $other instanceof ChangesListFilter ) {
 234                         $this->conflictingFilters[] = [
 235                                 'group' => $other->getGroup()->getName(),
 236                                 'filter' => $other->getName(),
 237                                 'globalDescription' => $globalDescription,
 238                                 'contextDescription' => $contextDescription,
 239                         ];
 240                 } else {
 241                         throw new MWException( 'You can only pass in a ChangesListFilterGroup or a ChangesListFilter' );
 242                 }
 243         }
 244
 245         /**
 246          * Marks that the current instance is (also) a superset of the filter passed in.
 247          * This can be called more than once.
 248          *
 249          * This means that anything in the results for the other filter is also in the
 250          * results for this one.
 251          *
 252          * @param ChangesListFilter The filter the current instance is a superset of
 253          */
 254         public function setAsSupersetOf( ChangesListFilter $other ) {
 255                 if ( $other->getGroup() !== $this->getGroup() ) {
 256                         throw new MWException( 'Supersets can only be defined for filters in the same group' );
 257                 }
 258
 259                 $this->subsetFilters[] = [
 260                         // It's always the same group, but this makes the representation
 261                         // more consistent with conflicts.
 262                         'group' => $other->getGroup()->getName(),
 263                         'filter' => $other->getName(),
 264                 ];
 265         }
 266
 267         /**
 268          * @return string Name, e.g. hideanons
 269          */
 270         public function getName() {
 271                 return $this->name;
 272         }
 273
 274         /**
 275          * @return ChangesListFilterGroup Group this belongs to
 276          */
 277         public function getGroup() {
 278                 return $this->group;
 279         }
 280
 281         /**
 282          * @return string i18n key of label for structured UI
 283          */
 284         public function getLabel() {
 285                 return $this->label;
 286         }
 287
 288         /**
 289          * @return string i18n key of description for structured UI
 290          */
 291         public function getDescription() {
 292                 return $this->description;
 293         }
 294
 295         /**
 296          * Checks whether the filter should display on the unstructured UI
 297          *
 298          * @param ChangesListSpecialPage $specialPage Current special page
 299          * @return bool Whether to display
 300          */
 301         abstract public function displaysOnUnstructuredUi( ChangesListSpecialPage $specialPage );
 302
 303         /**
 304          * Checks whether the filter should display on the structured UI
 305          * This refers to the exact filter.  See also isFeatureAvailableOnStructuredUi.
 306          *
 307          * @param ChangesListSpecialPage $specialPage Current special page
 308          * @return bool Whether to display
 309          */
 310         public function displaysOnStructuredUi( ChangesListSpecialPage $specialPage ) {
 311                 return $this->label !== null && $this->isAllowed( $specialPage );
 312         }
 313
 314         /**
 315          * Checks whether an equivalent feature for this filter is available on the
 316          * structured UI.
 317          *
 318          * This can either be the exact filter, or a new filter that replaces it.
 319          */
 320         public function isFeatureAvailableOnStructuredUi( ChangesListSpecialPage $specialPage ) {
 321                 return $this->displaysOnStructuredUi( $specialPage );
 322         }
 323
 324         /**
 325          * @return int Priority.  Higher value means higher up in the group list
 326          */
 327         public function getPriority() {
 328                 return $this->priority;
 329         }
 330
 331         /**
 332          * Checks whether the filter is allowed for the current context
 333          *
 334          * @param ChangesListSpecialPage $specialPage Current special page
 335          * @return bool Whether it is allowed
 336          */
 337         public function isAllowed( ChangesListSpecialPage $specialPage ) {
 338                 if ( $this->isAllowedCallable === null ) {
 339                         return true;
 340                 } else {
 341                         return call_user_func(
 342                                 $this->isAllowedCallable,
 343                                 get_class( $specialPage ),
 344                                 $specialPage->getContext()
 345                         );
 346                 }
 347         }
 348
 349         /**
 350          * Gets the CSS class
 351          *
 352          * @return string|null CSS class, or null if not defined
 353          */
 354         protected function getCssClass() {
 355                 if ( $this->cssClassSuffix !== null ) {
 356                         return ChangesList::CSS_CLASS_PREFIX . $this->cssClassSuffix;
 357                 } else {
 358                         return null;
 359                 }
 360         }
 361
 362         /**
 363          * Add CSS class if needed
 364          *
 365          * @param IContextSource $ctx Context source
 366          * @param RecentChange $rc Recent changes object
 367          * @param Non-associative array of CSS class names; appended to if needed
 368          */
 369         public function applyCssClassIfNeeded( IContextSource $ctx, RecentChange $rc, array &$classes ) {
 370                 if ( $this->isRowApplicableCallable === null ) {
 371                         return;
 372                 }
 373
 374                 if ( call_user_func( $this->isRowApplicableCallable, $ctx, $rc ) ) {
 375                         $classes[] = $this->getCssClass();
 376                 }
 377         }
 378
 379         /**
 380          * Gets the JS data required by the front-end of the structured UI
 381          *
 382          * @return array Associative array Data required by the front-end.  messageKeys is
 383          *  a special top-level value, with the value being an array of the message keys to
 384          *  send to the client.
 385          */
 386         public function getJsData() {
 387                 $output = [
 388                         'name' => $this->getName(),
 389                         'label' => $this->getLabel(),
 390                         'description' => $this->getDescription(),
 391                         'cssClass' => $this->getCssClass(),
 392                         'priority' => $this->priority,
 393                         'subset' => $this->subsetFilters,
 394                         'conflicts' => [],
 395                 ];
 396
 397                 $output['messageKeys'] = [
 398                         $this->getLabel(),
 399                         $this->getDescription(),
 400                 ];
 401
 402                 $conflicts = array_merge(
 403                         $this->conflictingGroups,
 404                         $this->conflictingFilters
 405                 );
 406
 407                 foreach ( $conflicts as $conflictInfo ) {
 408                         $output['conflicts'][] = $conflictInfo;
 409                         array_push(
 410                                 $output['messageKeys'],
 411                                 $conflictInfo['globalDescription'],
 412                                 $conflictInfo['contextDescription']
 413                         );
 414                 }
 415
 416                 return $output;
 417         }
 418 }