Page Menu
Home
WickedGov Phorge
Search
Configure Global Search
Log In
Files
F7416134
ChangesListFilter.php
No One
Temporary
Actions
Download File
Edit File
Delete File
View Transforms
Subscribe
Flag For Later
Award Token
Size
14 KB
Referenced Files
None
Subscribers
None
ChangesListFilter.php
View Options
<?php
/**
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @file
*/
use
MediaWiki\Context\IContextSource
;
use
MediaWiki\Html\FormOptions
;
/**
* Represents a filter (used on ChangesListSpecialPage and descendants)
*
* @since 1.29
* @ingroup RecentChanges
* @author Matthew Flaschen
*/
abstract
class
ChangesListFilter
{
/**
* Filter name
*
* @var string
*/
protected
$name
;
/**
* CSS class suffix used for attribution, e.g. 'bot'.
*
* In this example, if bot actions are included in the result set, this CSS class
* will then be included in all bot-flagged actions.
*
* @var string|null
*/
protected
$cssClassSuffix
;
/**
* Callable that returns true if and only if a row is attributed to this filter
*
* @var callable
*/
protected
$isRowApplicableCallable
;
/**
* Group. ChangesListFilterGroup this belongs to
*
* @var ChangesListFilterGroup
*/
protected
$group
;
/**
* i18n key of label for structured UI
*
* @var string
*/
protected
$label
;
/**
* i18n key of description for structured UI
*
* @var string
*/
protected
$description
;
/**
* Array of associative arrays with conflict information. See
* setUnidirectionalConflict
*
* @var array
*/
protected
$conflictingGroups
=
[];
/**
* Array of associative arrays with conflict information. See
* setUnidirectionalConflict
*
* @var array
*/
protected
$conflictingFilters
=
[];
/**
* Array of associative arrays with subset information
*
* @var array
*/
protected
$subsetFilters
=
[];
/**
* Priority integer. Higher value means higher up in the group's filter list.
*
* @var int
*/
protected
$priority
;
/**
* @var string
*/
protected
$defaultHighlightColor
;
private
const
RESERVED_NAME_CHAR
=
'_'
;
/**
* Creates a new filter with the specified configuration, and registers it to the
* specified group.
*
* It infers which UI (it can be either or both) to display the filter on based on
* which messages are provided.
*
* If 'label' is provided, it will be displayed on the structured UI. Thus,
* 'label', 'description', and sub-class parameters are optional depending on which
* UI it's for.
*
* @param array $filterDefinition ChangesListFilter definition
* * $filterDefinition['name'] string Name of filter; use lowercase with no
* punctuation
* * $filterDefinition['cssClassSuffix'] string CSS class suffix, used to mark
* that a particular row belongs to this filter (when a row is included by the
* filter) (optional)
* * $filterDefinition['isRowApplicableCallable'] callable Callable taking two parameters, the
* IContextSource, and the RecentChange object for the row, and returning true if
* the row is attributed to this filter. The above CSS class will then be
* automatically added (optional, required if cssClassSuffix is used).
* * $filterDefinition['group'] ChangesListFilterGroup Group. Filter group this
* belongs to.
* * $filterDefinition['label'] string i18n key of label for structured UI.
* * $filterDefinition['description'] string i18n key of description for structured
* UI.
* * $filterDefinition['priority'] int Priority integer. Higher value means higher
* up in the group's filter list.
* @phpcs:ignore Generic.Files.LineLength
* @phan-param array{name:string,cssClassSuffix?:string,isRowApplicableCallable?:callable,group:ChangesListFilterGroup,label:string,description:string,priority:int} $filterDefinition
*/
public
function
__construct
(
array
$filterDefinition
)
{
if
(
isset
(
$filterDefinition
[
'group'
]
)
)
{
$this
->
group
=
$filterDefinition
[
'group'
];
}
else
{
throw
new
InvalidArgumentException
(
'You must use
\'
group
\'
to specify the '
.
'ChangesListFilterGroup this filter belongs to'
);
}
if
(
strpos
(
$filterDefinition
[
'name'
],
self
::
RESERVED_NAME_CHAR
)
!==
false
)
{
throw
new
InvalidArgumentException
(
'Filter names may not contain
\'
'
.
self
::
RESERVED_NAME_CHAR
.
'
\'
. Use the naming convention:
\'
lowercase
\'
'
);
}
if
(
$this
->
group
->
getFilter
(
$filterDefinition
[
'name'
]
)
)
{
throw
new
InvalidArgumentException
(
'Two filters in a group cannot have the '
.
"same name: '{$filterDefinition['name']}'"
);
}
$this
->
name
=
$filterDefinition
[
'name'
];
if
(
isset
(
$filterDefinition
[
'cssClassSuffix'
]
)
)
{
$this
->
cssClassSuffix
=
$filterDefinition
[
'cssClassSuffix'
];
// @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset Documented as required
$this
->
isRowApplicableCallable
=
$filterDefinition
[
'isRowApplicableCallable'
];
}
if
(
isset
(
$filterDefinition
[
'label'
]
)
)
{
$this
->
label
=
$filterDefinition
[
'label'
];
$this
->
description
=
$filterDefinition
[
'description'
];
}
$this
->
priority
=
$filterDefinition
[
'priority'
];
$this
->
group
->
registerFilter
(
$this
);
}
/**
* Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with this object.
*
* WARNING: This means there is a conflict when both things are *shown*
* (not filtered out), even for the hide-based filters. So e.g. conflicting with
* 'hideanons' means there is a conflict if only anonymous users are *shown*.
*
* @param ChangesListFilterGroup|ChangesListFilter $other
* @param string $globalKey i18n key for top-level conflict message
* @param string $forwardKey i18n key for conflict message in this
* direction (when in UI context of $this object)
* @param string $backwardKey i18n key for conflict message in reverse
* direction (when in UI context of $other object)
*/
public
function
conflictsWith
(
$other
,
string
$globalKey
,
string
$forwardKey
,
string
$backwardKey
)
{
$this
->
setUnidirectionalConflict
(
$other
,
$globalKey
,
$forwardKey
);
$other
->
setUnidirectionalConflict
(
$this
,
$globalKey
,
$backwardKey
);
}
/**
* Marks that the given ChangesListFilterGroup or ChangesListFilter conflicts with
* this object.
*
* Internal use ONLY.
*
* @param ChangesListFilterGroup|ChangesListFilter $other
* @param string $globalDescription i18n key for top-level conflict message
* @param string $contextDescription i18n key for conflict message in this
* direction (when in UI context of $this object)
*/
public
function
setUnidirectionalConflict
(
$other
,
$globalDescription
,
$contextDescription
)
{
if
(
$other
instanceof
ChangesListFilterGroup
)
{
$this
->
conflictingGroups
[]
=
[
'group'
=>
$other
->
getName
(),
'groupObject'
=>
$other
,
'globalDescription'
=>
$globalDescription
,
'contextDescription'
=>
$contextDescription
,
];
}
elseif
(
$other
instanceof
ChangesListFilter
)
{
$this
->
conflictingFilters
[]
=
[
'group'
=>
$other
->
getGroup
()->
getName
(),
'filter'
=>
$other
->
getName
(),
'filterObject'
=>
$other
,
'globalDescription'
=>
$globalDescription
,
'contextDescription'
=>
$contextDescription
,
];
}
else
{
throw
new
InvalidArgumentException
(
'You can only pass in a ChangesListFilterGroup or a ChangesListFilter'
);
}
}
/**
* Marks that the current instance is (also) a superset of the filter passed in.
* This can be called more than once.
*
* This means that anything in the results for the other filter is also in the
* results for this one.
*
* @param ChangesListFilter $other The filter the current instance is a superset of
*/
public
function
setAsSupersetOf
(
ChangesListFilter
$other
)
{
if
(
$other
->
getGroup
()
!==
$this
->
getGroup
()
)
{
throw
new
InvalidArgumentException
(
'Supersets can only be defined for filters in the same group'
);
}
$this
->
subsetFilters
[]
=
[
// It's always the same group, but this makes the representation
// more consistent with conflicts.
'group'
=>
$other
->
getGroup
()->
getName
(),
'filter'
=>
$other
->
getName
(),
];
}
/**
* @return string Name, e.g. hideanons
*/
public
function
getName
()
{
return
$this
->
name
;
}
/**
* @return ChangesListFilterGroup Group this belongs to
*/
public
function
getGroup
()
{
return
$this
->
group
;
}
/**
* @return string i18n key of label for structured UI
*/
public
function
getLabel
()
{
return
$this
->
label
;
}
/**
* @return string i18n key of description for structured UI
*/
public
function
getDescription
()
{
return
$this
->
description
;
}
/**
* Checks whether the filter should display on the unstructured UI
*
* @return bool Whether to display
*/
abstract
public
function
displaysOnUnstructuredUi
();
/**
* Checks whether the filter should display on the structured UI
* This refers to the exact filter. See also isFeatureAvailableOnStructuredUi.
*
* @return bool Whether to display
*/
public
function
displaysOnStructuredUi
()
{
return
$this
->
label
!==
null
;
}
/**
* Checks whether an equivalent feature for this filter is available on the
* structured UI.
*
* This can either be the exact filter, or a new filter that replaces it.
* @return bool
*/
public
function
isFeatureAvailableOnStructuredUi
()
{
return
$this
->
displaysOnStructuredUi
();
}
/**
* @return int Priority. Higher value means higher up in the group list
*/
public
function
getPriority
()
{
return
$this
->
priority
;
}
/**
* Gets the CSS class
*
* @return string|null CSS class, or null if not defined
*/
protected
function
getCssClass
()
{
if
(
$this
->
cssClassSuffix
!==
null
)
{
return
ChangesList
::
CSS_CLASS_PREFIX
.
$this
->
cssClassSuffix
;
}
else
{
return
null
;
}
}
/**
* Add CSS class if needed
*
* @param IContextSource $ctx Context source
* @param RecentChange $rc Recent changes object
* @param array &$classes Non-associative array of CSS class names; appended to if needed
*/
public
function
applyCssClassIfNeeded
(
IContextSource
$ctx
,
RecentChange
$rc
,
array
&
$classes
)
{
if
(
$this
->
isRowApplicableCallable
===
null
)
{
return
;
}
if
(
call_user_func
(
$this
->
isRowApplicableCallable
,
$ctx
,
$rc
)
)
{
$classes
[]
=
$this
->
getCssClass
();
}
}
/**
* Gets the JS data required by the front-end of the structured UI
*
* @return array Associative array Data required by the front-end. messageKeys is
* a special top-level value, with the value being an array of the message keys to
* send to the client.
*/
public
function
getJsData
()
{
$output
=
[
'name'
=>
$this
->
getName
(),
'label'
=>
$this
->
getLabel
(),
'description'
=>
$this
->
getDescription
(),
'cssClass'
=>
$this
->
getCssClass
(),
'priority'
=>
$this
->
priority
,
'subset'
=>
$this
->
subsetFilters
,
'conflicts'
=>
[],
'defaultHighlightColor'
=>
$this
->
defaultHighlightColor
];
$output
[
'messageKeys'
]
=
[
$this
->
getLabel
(),
$this
->
getDescription
(),
];
$conflicts
=
array_merge
(
$this
->
conflictingGroups
,
$this
->
conflictingFilters
);
foreach
(
$conflicts
as
$conflictInfo
)
{
unset
(
$conflictInfo
[
'filterObject'
]
);
unset
(
$conflictInfo
[
'groupObject'
]
);
$output
[
'conflicts'
][]
=
$conflictInfo
;
array_push
(
$output
[
'messageKeys'
],
$conflictInfo
[
'globalDescription'
],
$conflictInfo
[
'contextDescription'
]
);
}
return
$output
;
}
/**
* Checks whether this filter is selected in the provided options
*
* @param FormOptions $opts
* @return bool
*/
abstract
public
function
isSelected
(
FormOptions
$opts
);
/**
* Get groups conflicting with this filter
*
* @return ChangesListFilterGroup[]
*/
public
function
getConflictingGroups
()
{
return
array_column
(
$this
->
conflictingGroups
,
'groupObject'
);
}
/**
* Get filters conflicting with this filter
*
* @return ChangesListFilter[]
*/
public
function
getConflictingFilters
()
{
return
array_column
(
$this
->
conflictingFilters
,
'filterObject'
);
}
/**
* Check if the conflict with a group is currently "active"
*
* @param ChangesListFilterGroup $group
* @param FormOptions $opts
* @return bool
*/
public
function
activelyInConflictWithGroup
(
ChangesListFilterGroup
$group
,
FormOptions
$opts
)
{
if
(
$group
->
anySelected
(
$opts
)
&&
$this
->
isSelected
(
$opts
)
)
{
/** @var ChangesListFilter $siblingFilter */
foreach
(
$this
->
getSiblings
()
as
$siblingFilter
)
{
if
(
$siblingFilter
->
isSelected
(
$opts
)
&&
!
$siblingFilter
->
hasConflictWithGroup
(
$group
)
)
{
return
false
;
}
}
return
true
;
}
return
false
;
}
private
function
hasConflictWithGroup
(
ChangesListFilterGroup
$group
)
{
return
in_array
(
$group
,
$this
->
getConflictingGroups
()
);
}
/**
* Check if the conflict with a filter is currently "active"
*
* @param ChangesListFilter $filter
* @param FormOptions $opts
* @return bool
*/
public
function
activelyInConflictWithFilter
(
ChangesListFilter
$filter
,
FormOptions
$opts
)
{
if
(
$this
->
isSelected
(
$opts
)
&&
$filter
->
isSelected
(
$opts
)
)
{
/** @var ChangesListFilter $siblingFilter */
foreach
(
$this
->
getSiblings
()
as
$siblingFilter
)
{
if
(
$siblingFilter
->
isSelected
(
$opts
)
&&
!
$siblingFilter
->
hasConflictWithFilter
(
$filter
)
)
{
return
false
;
}
}
return
true
;
}
return
false
;
}
private
function
hasConflictWithFilter
(
ChangesListFilter
$filter
)
{
return
in_array
(
$filter
,
$this
->
getConflictingFilters
()
);
}
/**
* Get filters in the same group
*
* @return ChangesListFilter[]
*/
protected
function
getSiblings
()
{
return
array_filter
(
$this
->
getGroup
()->
getFilters
(),
function
(
$filter
)
{
return
$filter
!==
$this
;
}
);
}
/**
* @param string $defaultHighlightColor
*/
public
function
setDefaultHighlightColor
(
$defaultHighlightColor
)
{
$this
->
defaultHighlightColor
=
$defaultHighlightColor
;
}
}
File Metadata
Details
Attached
Mime Type
text/x-php
Expires
Sun, Nov 22, 02:33 (1 d, 11 h)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
fd/a9/212c69c501da5eaf6c8e25d3d66d
Default Alt Text
ChangesListFilter.php (14 KB)
Attached To
Mode
rMWPROD MediaWiki Production
Attached
Detach File
Event Timeline
Log In to Comment