3 * Represents a filter (used on ChangesListSpecialPage and descendants)
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.
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.
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
22 * @author Matthew Flaschen
26 * Represents a filter (used on ChangesListSpecialPage and descendants)
30 abstract class ChangesListFilter
{
39 * CSS class suffix used for attribution, e.g. 'bot'.
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.
44 * @var string|null $cssClassSuffix
46 protected $cssClassSuffix;
49 * Callable that returns true if and only if a row is attributed to this filter
51 * @var callable $isRowApplicableCallable
53 protected $isRowApplicableCallable;
56 * Group. ChangesListFilterGroup this belongs to
58 * @var ChangesListFilterGroup $group
63 * i18n key of label for structured UI
70 * i18n key of description for structured UI
72 * @var string $description
74 protected $description;
77 * Callable used to check whether this filter is allowed to take effect
79 * @var callable $isAllowedCallable
81 protected $isAllowedCallable;
84 * List of conflicting groups
86 * @var array $conflictingGroups Array of associative arrays with conflict
87 * information. See setUnidirectionalConflict
89 protected $conflictingGroups = [];
92 * List of conflicting filters
94 * @var array $conflictingFilters Array of associative arrays with conflict
95 * information. See setUnidirectionalConflict
97 protected $conflictingFilters = [];
100 * List of filters that are a subset of the current filter
102 * @var array $subsetFilters Array of associative arrays with subset information
104 protected $subsetFilters = [];
107 * Priority integer. Higher value means higher up in the group's filter list.
109 * @var string $priority
113 const RESERVED_NAME_CHAR
= '_';
116 * Creates a new filter with the specified configuration, and registers it to the
119 * It infers which UI (it can be either or both) to display the filter on based on
120 * which messages are provided.
122 * If 'label' is provided, it will be displayed on the structured UI. Thus,
123 * 'label', 'description', and sub-class parameters are optional depending on which
126 * @param array $filterDefinition ChangesListFilter definition
128 * $filterDefinition['name'] string Name of filter; use lowercase with no
130 * $filterDefinition['cssClassSuffix'] string CSS class suffix, used to mark
131 * that a particular row belongs to this filter (when a row is included by the
133 * $filterDefinition['isRowApplicableCallable'] Callable taking two parameters, the
134 * IContextSource, and the RecentChange object for the row, and returning true if
135 * the row is attributed to this filter. The above CSS class will then be
136 * automatically added (optional, required if cssClassSuffix is used).
137 * $filterDefinition['group'] ChangesListFilterGroup Group. Filter group this
139 * $filterDefinition['label'] string i18n key of label for structured UI.
140 * $filterDefinition['description'] string i18n key of description for structured
142 * $filterDefinition['isAllowedCallable'] callable Callable taking two parameters,
143 * the class name of the special page and an IContextSource, and returning true
144 * if and only if the current user is permitted to use this filter on the current
145 * wiki. If it returns false, it will both hide the UI (in all UIs) and prevent
146 * the DB query modification from taking effect. (optional, defaults to allowed)
147 * $filterDefinition['priority'] int Priority integer. Higher value means higher
148 * up in the group's filter list.
150 public function __construct( array $filterDefinition ) {
151 if ( isset( $filterDefinition['group'] ) ) {
152 $this->group
= $filterDefinition['group'];
154 throw new MWException( 'You must use \'group\' to specify the ' .
155 'ChangesListFilterGroup this filter belongs to' );
158 if ( strpos( $filterDefinition['name'], self
::RESERVED_NAME_CHAR
) !== false ) {
159 throw new MWException( 'Filter names may not contain \'' .
160 self
::RESERVED_NAME_CHAR
.
161 '\'. Use the naming convention: \'lowercase\''
165 if ( $this->group
->getFilter( $filterDefinition['name'] ) ) {
166 throw new MWException( 'Two filters in a group cannot have the ' .
167 "same name: '{$filterDefinition['name']}'" );
170 $this->name
= $filterDefinition['name'];
172 if ( isset( $filterDefinition['cssClassSuffix'] ) ) {
173 $this->cssClassSuffix
= $filterDefinition['cssClassSuffix'];
174 $this->isRowApplicableCallable
= $filterDefinition['isRowApplicableCallable'];
177 if ( isset( $filterDefinition['label'] ) ) {
178 $this->label
= $filterDefinition['label'];
179 $this->description
= $filterDefinition['description'];
182 if ( isset( $filterDefinition['isAllowedCallable'] ) ) {
183 $this->isAllowedCallable
= $filterDefinition['isAllowedCallable'];
186 $this->priority
= $filterDefinition['priority'];
188 $this->group
->registerFilter( $this );
192 * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with this object.
194 * WARNING: This means there is a conflict when both things are *shown*
195 * (not filtered out), even for the hide-based filters. So e.g. conflicting with
196 * 'hideanons' means there is a conflict if only anonymous users are *shown*.
198 * @param ChangesListFilterGroup|ChangesListFilter $other Other
199 * ChangesListFilterGroup or ChangesListFilter
200 * @param string $globalKey i18n key for top-level conflict message
201 * @param string $forwardKey i18n key for conflict message in this
202 * direction (when in UI context of $this object)
203 * @param string $backwardKey i18n key for conflict message in reverse
204 * direction (when in UI context of $other object)
206 public function conflictsWith( $other, $globalKey, $forwardKey,
209 if ( $globalKey === null ||
$forwardKey === null ||
210 $backwardKey === null ) {
212 throw new MWException( 'All messages must be specified' );
215 $this->setUnidirectionalConflict(
221 $other->setUnidirectionalConflict(
229 * Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with
234 * @param ChangesListFilterGroup|ChangesListFilter $other Other
235 * ChangesListFilterGroup or ChangesListFilter
236 * @param string $globalDescription i18n key for top-level conflict message
237 * @param string $contextDescription i18n key for conflict message in this
238 * direction (when in UI context of $this object)
240 public function setUnidirectionalConflict( $other, $globalDescription,
241 $contextDescription ) {
243 if ( $other instanceof ChangesListFilterGroup
) {
244 $this->conflictingGroups
[] = [
245 'group' => $other->getName(),
246 'globalDescription' => $globalDescription,
247 'contextDescription' => $contextDescription,
249 } elseif ( $other instanceof ChangesListFilter
) {
250 $this->conflictingFilters
[] = [
251 'group' => $other->getGroup()->getName(),
252 'filter' => $other->getName(),
253 'globalDescription' => $globalDescription,
254 'contextDescription' => $contextDescription,
257 throw new MWException( 'You can only pass in a ChangesListFilterGroup or a ChangesListFilter' );
262 * Marks that the current instance is (also) a superset of the filter passed in.
263 * This can be called more than once.
265 * This means that anything in the results for the other filter is also in the
266 * results for this one.
268 * @param ChangesListFilter The filter the current instance is a superset of
270 public function setAsSupersetOf( ChangesListFilter
$other ) {
271 if ( $other->getGroup() !== $this->getGroup() ) {
272 throw new MWException( 'Supersets can only be defined for filters in the same group' );
275 $this->subsetFilters
[] = [
276 // It's always the same group, but this makes the representation
277 // more consistent with conflicts.
278 'group' => $other->getGroup()->getName(),
279 'filter' => $other->getName(),
284 * @return string Name, e.g. hideanons
286 public function getName() {
291 * @return ChangesListFilterGroup Group this belongs to
293 public function getGroup() {
298 * @return string i18n key of label for structured UI
300 public function getLabel() {
305 * @return string i18n key of description for structured UI
307 public function getDescription() {
308 return $this->description
;
312 * Checks whether the filter should display on the unstructured UI
314 * @param ChangesListSpecialPage $specialPage Current special page
315 * @return bool Whether to display
317 abstract public function displaysOnUnstructuredUi( ChangesListSpecialPage
$specialPage );
320 * Checks whether the filter should display on the structured UI
321 * This refers to the exact filter. See also isFeatureAvailableOnStructuredUi.
323 * @param ChangesListSpecialPage $specialPage Current special page
324 * @return bool Whether to display
326 public function displaysOnStructuredUi( ChangesListSpecialPage
$specialPage ) {
327 return $this->label
!== null && $this->isAllowed( $specialPage );
331 * Checks whether an equivalent feature for this filter is available on the
334 * This can either be the exact filter, or a new filter that replaces it.
336 public function isFeatureAvailableOnStructuredUi( ChangesListSpecialPage
$specialPage ) {
337 return $this->displaysOnStructuredUi( $specialPage );
341 * @return int Priority. Higher value means higher up in the group list
343 public function getPriority() {
344 return $this->priority
;
348 * Checks whether the filter is allowed for the current context
350 * @param ChangesListSpecialPage $specialPage Current special page
351 * @return bool Whether it is allowed
353 public function isAllowed( ChangesListSpecialPage
$specialPage ) {
354 if ( $this->isAllowedCallable
=== null ) {
357 return call_user_func(
358 $this->isAllowedCallable
,
359 get_class( $specialPage ),
360 $specialPage->getContext()
368 * @return string|null CSS class, or null if not defined
370 protected function getCssClass() {
371 if ( $this->cssClassSuffix
!== null ) {
372 return ChangesList
::CSS_CLASS_PREFIX
. $this->cssClassSuffix
;
379 * Add CSS class if needed
381 * @param IContextSource $ctx Context source
382 * @param RecentChange $rc Recent changes object
383 * @param Non-associative array of CSS class names; appended to if needed
385 public function applyCssClassIfNeeded( IContextSource
$ctx, RecentChange
$rc, array &$classes ) {
386 if ( $this->isRowApplicableCallable
=== null ) {
390 if ( call_user_func( $this->isRowApplicableCallable
, $ctx, $rc ) ) {
391 $classes[] = $this->getCssClass();
396 * Gets the JS data required by the front-end of the structured UI
398 * @return array Associative array Data required by the front-end. messageKeys is
399 * a special top-level value, with the value being an array of the message keys to
400 * send to the client.
402 public function getJsData() {
404 'name' => $this->getName(),
405 'label' => $this->getLabel(),
406 'description' => $this->getDescription(),
407 'cssClass' => $this->getCssClass(),
408 'priority' => $this->priority
,
409 'subset' => $this->subsetFilters
,
413 $output['messageKeys'] = [
415 $this->getDescription(),
418 $conflicts = array_merge(
419 $this->conflictingGroups
,
420 $this->conflictingFilters
423 foreach ( $conflicts as $conflictInfo ) {
424 $output['conflicts'][] = $conflictInfo;
426 $output['messageKeys'],
427 $conflictInfo['globalDescription'],
428 $conflictInfo['contextDescription']