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