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