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