includes/changes/ChangesListBooleanFilter.php

   1 <?php
   2 /**
   3  * Represents a hide-based boolean 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 use Wikimedia\Rdbms\IDatabase;
  26
  27 /**
  28  * An individual filter in a boolean group
  29  *
  30  * @since 1.29
  31  */
  32 class ChangesListBooleanFilter extends ChangesListFilter {
  33         // This can sometimes be different on Special:RecentChanges
  34         // and Special:Watchlist, due to the double-legacy hooks
  35         // (SpecialRecentChangesFilters and SpecialWatchlistFilters)
  36
  37         // but there will be separate sets of ChangesListFilterGroup and ChangesListFilter instances
  38         // for those pages (it should work even if they're both loaded
  39         // at once, but that can't happen).
  40         /**
  41          * Main unstructured UI i18n key
  42          *
  43          * @var string $showHide
  44          */
  45         protected $showHide;
  46
  47         /**
  48          * Whether there is a feature designed to replace this filter available on the
  49          * structured UI
  50          *
  51          * @var bool $isReplacedInStructuredUi
  52          */
  53         protected $isReplacedInStructuredUi;
  54
  55         /**
  56          * Default
  57          *
  58          * @var bool $defaultValue
  59          */
  60         protected $defaultValue;
  61
  62         /**
  63          * Callable used to do the actual query modification; see constructor
  64          *
  65          * @var callable $queryCallable
  66          */
  67         protected $queryCallable;
  68
  69         /**
  70          * Value that defined when this filter is considered active
  71          *
  72          * @var bool $activeValue
  73          */
  74         protected $activeValue;
  75
  76         /**
  77          * Whether this filter is visible somewhere (legacy form or structured UI).
  78          *
  79          * @var bool $isVisible
  80          */
  81         protected $isVisible;
  82
  83         /**
  84          * Create a new filter with the specified configuration.
  85          *
  86          * It infers which UI (it can be either or both) to display the filter on based on
  87          * which messages are provided.
  88          *
  89          * If 'label' is provided, it will be displayed on the structured UI.  If
  90          * 'showHide' is provided, it will be displayed on the unstructured UI.  Thus,
  91          * 'label', 'description', and 'showHide' are optional depending on which UI
  92          * it's for.
  93          *
  94          * @param array $filterDefinition ChangesListFilter definition
  95          * * $filterDefinition['name'] string Name.  Used as URL parameter.
  96          * * $filterDefinition['group'] ChangesListFilterGroup Group.  Filter group this
  97          *     belongs to.
  98          * * $filterDefinition['label'] string i18n key of label for structured UI.
  99          * * $filterDefinition['description'] string i18n key of description for structured
 100          *     UI.
 101          * * $filterDefinition['showHide'] string Main i18n key used for unstructured UI.
 102          * * $filterDefinition['isReplacedInStructuredUi'] bool Whether there is an
 103          *     equivalent feature available in the structured UI; this is optional, defaulting
 104          *     to true.  It does not need to be set if the exact same filter is simply visible
 105          *     on both.
 106          * * $filterDefinition['default'] bool Default
 107          * * $filterDefinition['activeValue'] bool This filter is considered active when
 108          *     its value is equal to its activeValue. Default is true.
 109          * * $filterDefinition['isVisible'] bool This filter is visible in the legacy form or
 110          *     structured UI. Default is true.
 111          * * $filterDefinition['priority'] int Priority integer.  Higher value means higher
 112          *     up in the group's filter list.
 113          * * $filterDefinition['queryCallable'] callable Callable accepting parameters, used
 114          *     to implement filter's DB query modification.  Required, except for legacy
 115          *     filters that still use the query hooks directly.  Callback parameters:
 116          *      * string $specialPageClassName Class name of current special page
 117          *      * IContextSource $context Context, for e.g. user
 118          *      * IDatabase $dbr Database, for addQuotes, makeList, and similar
 119          *      * array &$tables Array of tables; see IDatabase::select $table
 120          *      * array &$fields Array of fields; see IDatabase::select $vars
 121          *      * array &$conds Array of conditions; see IDatabase::select $conds
 122          *      * array &$query_options Array of query options; see IDatabase::select $options
 123          *      * array &$join_conds Array of join conditions; see IDatabase::select $join_conds
 124          */
 125         public function __construct( $filterDefinition ) {
 126                 parent::__construct( $filterDefinition );
 127
 128                 if ( isset( $filterDefinition['showHide'] ) ) {
 129                         $this->showHide = $filterDefinition['showHide'];
 130                 }
 131
 132                 if ( isset( $filterDefinition['isReplacedInStructuredUi'] ) ) {
 133                         $this->isReplacedInStructuredUi = $filterDefinition['isReplacedInStructuredUi'];
 134                 } else {
 135                         $this->isReplacedInStructuredUi = false;
 136                 }
 137
 138                 if ( isset( $filterDefinition['default'] ) ) {
 139                         $this->defaultValue = $filterDefinition['default'];
 140                 } else {
 141                         throw new MWException( 'You must set a default' );
 142                 }
 143
 144                 if ( isset( $filterDefinition['queryCallable'] ) ) {
 145                         $this->queryCallable = $filterDefinition['queryCallable'];
 146                 }
 147
 148                 if ( isset( $filterDefinition['activeValue'] ) ) {
 149                         $this->activeValue = $filterDefinition['activeValue'];
 150                 } else {
 151                         $this->activeValue = true;
 152                 }
 153
 154                 if ( isset( $filterDefinition['isVisible'] ) ) {
 155                         $this->isVisible = $filterDefinition['isVisible'];
 156                 } else {
 157                         $this->isVisible = true;
 158                 }
 159         }
 160
 161         /**
 162          * Get the default value
 163          *
 164          * @param bool $structuredUI Are we currently showing the structured UI
 165          * @return bool|null Default value
 166          */
 167         public function getDefault( $structuredUI = false ) {
 168                 return $this->isReplacedInStructuredUi && $structuredUI ?
 169                         !$this->activeValue :
 170                         $this->defaultValue;
 171         }
 172
 173         /**
 174          * Sets default
 175          *
 176          * @param bool $defaultValue
 177          */
 178         public function setDefault( $defaultValue ) {
 179                 $this->defaultValue = $defaultValue;
 180         }
 181
 182         /**
 183          * @return string Main i18n key for unstructured UI
 184          */
 185         public function getShowHide() {
 186                 return $this->showHide;
 187         }
 188
 189         /**
 190          * @inheritDoc
 191          */
 192         public function displaysOnUnstructuredUi() {
 193                 return !!$this->showHide;
 194         }
 195
 196         /**
 197          * @inheritDoc
 198          */
 199         public function isFeatureAvailableOnStructuredUi() {
 200                 return $this->isReplacedInStructuredUi ||
 201                         parent::isFeatureAvailableOnStructuredUi();
 202         }
 203
 204         /**
 205          * Modifies the query to include the filter.  This is only called if the filter is
 206          * in effect (taking into account the default).
 207          *
 208          * @param IDatabase $dbr Database, for addQuotes, makeList, and similar
 209          * @param ChangesListSpecialPage $specialPage Current special page
 210          * @param array &$tables Array of tables; see IDatabase::select $table
 211          * @param array &$fields Array of fields; see IDatabase::select $vars
 212          * @param array &$conds Array of conditions; see IDatabase::select $conds
 213          * @param array &$query_options Array of query options; see IDatabase::select $options
 214          * @param array &$join_conds Array of join conditions; see IDatabase::select $join_conds
 215          */
 216         public function modifyQuery( IDatabase $dbr, ChangesListSpecialPage $specialPage,
 217                 &$tables, &$fields, &$conds, &$query_options, &$join_conds
 218         ) {
 219                 if ( $this->queryCallable === null ) {
 220                         return;
 221                 }
 222
 223                 call_user_func_array(
 224                         $this->queryCallable,
 225                         [
 226                                 get_class( $specialPage ),
 227                                 $specialPage->getContext(),
 228                                 $dbr,
 229                                 &$tables,
 230                                 &$fields,
 231                                 &$conds,
 232                                 &$query_options,
 233                                 &$join_conds
 234                         ]
 235                 );
 236         }
 237
 238         /**
 239          * @inheritDoc
 240          */
 241         public function getJsData() {
 242                 $output = parent::getJsData();
 243
 244                 $output['default'] = $this->defaultValue;
 245
 246                 return $output;
 247         }
 248
 249         /**
 250          * @inheritDoc
 251          */
 252         public function isSelected( FormOptions $opts ) {
 253                 return !$opts[ $this->getName() ] &&
 254                         array_filter( $this->getSiblings(), function ( $sibling ) use ( $opts ) {
 255                                 return $opts[ $sibling->getName() ];
 256                         } );
 257         }
 258
 259         /**
 260          * @param FormOptions $opts Query parameters merged with defaults
 261          * @param bool $isStructuredUI Whether the structured UI is currently enabled
 262          * @return bool Whether this filter should be considered active
 263          */
 264         public function isActive( FormOptions $opts, $isStructuredUI ) {
 265                 if ( $this->isReplacedInStructuredUi && $isStructuredUI ) {
 266                         return false;
 267                 }
 268
 269                 return $opts[ $this->getName() ] === $this->activeValue;
 270         }
 271
 272         /**
 273          * @return bool Whether this filter is visible anywhere
 274          */
 275         public function isVisible() {
 276                 return $this->isVisible;
 277         }
 278 }