--- /dev/null
+<?php
+/**
+ * Represents a filter (used on ChangesListSpecialPage and descendants)
+ *
+ * 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
+ * @license GPL 2+
+ * @author Matthew Flaschen
+ */
+
+/**
+ * Represents a filter (used on ChangesListSpecialPage and descendants)
+ *
+ * @since 1.29
+ */
+abstract class ChangesListFilter {
+ /**
+ * Filter name
+ *
+ * @var string $name
+ */
+ 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 $cssClassSuffix
+ */
+ protected $cssClassSuffix;
+
+ /**
+ * Callable that returns true if and only if a row is attributed to this filter
+ *
+ * @var callable $isRowApplicableCallable
+ */
+ protected $isRowApplicableCallable;
+
+ /**
+ * Group. ChangesListFilterGroup this belongs to
+ *
+ * @var ChangesListFilterGroup $group
+ */
+ protected $group;
+
+ /**
+ * i18n key of label for structured UI
+ *
+ * @var string $label
+ */
+ protected $label;
+
+ /**
+ * i18n key of description for structured UI
+ *
+ * @var string $description
+ */
+ protected $description;
+
+ /**
+ * Array of associative arrays with conflict information. See
+ * setUnidirectionalConflict
+ *
+ * @var array $conflictingGroups
+ */
+ protected $conflictingGroups = [];
+
+ /**
+ * Array of associative arrays with conflict information. See
+ * setUnidirectionalConflict
+ *
+ * @var array $conflictingFilters
+ */
+ protected $conflictingFilters = [];
+
+ /**
+ * Array of associative arrays with subset information
+ *
+ * @var array $subsetFilters
+ */
+ protected $subsetFilters = [];
+
+ /**
+ * Priority integer. Higher value means higher up in the group's filter list.
+ *
+ * @var string $priority
+ */
+ protected $priority;
+
+ 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 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.
+ */
+ public function __construct( array $filterDefinition ) {
+ if ( isset( $filterDefinition['group'] ) ) {
+ $this->group = $filterDefinition['group'];
+ } else {
+ throw new MWException( 'You must use \'group\' to specify the ' .
+ 'ChangesListFilterGroup this filter belongs to' );
+ }
+
+ if ( strpos( $filterDefinition['name'], self::RESERVED_NAME_CHAR ) !== false ) {
+ throw new MWException( 'Filter names may not contain \'' .
+ self::RESERVED_NAME_CHAR .
+ '\'. Use the naming convention: \'lowercase\''
+ );
+ }
+
+ if ( $this->group->getFilter( $filterDefinition['name'] ) ) {
+ throw new MWException( 'Two filters in a group cannot have the ' .
+ "same name: '{$filterDefinition['name']}'" );
+ }
+
+ $this->name = $filterDefinition['name'];
+
+ if ( isset( $filterDefinition['cssClassSuffix'] ) ) {
+ $this->cssClassSuffix = $filterDefinition['cssClassSuffix'];
+ $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 Other
+ * ChangesListFilterGroup or ChangesListFilter
+ * @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, $globalKey, $forwardKey, $backwardKey ) {
+ if ( $globalKey === null || $forwardKey === null || $backwardKey === null ) {
+ throw new MWException( 'All messages must be specified' );
+ }
+
+ $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 Other
+ * ChangesListFilterGroup or ChangesListFilter
+ * @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 MWException( '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 MWException( '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' => [],
+ ];
+
+ $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_map(
+ function ( $conflictDesc ) {
+ return $conflictDesc[ 'groupObject' ];
+ },
+ $this->conflictingGroups
+ );
+ }
+
+ /**
+ * Get filters conflicting with this filter
+ *
+ * @return ChangesListFilter[]
+ */
+ public function getConflictingFilters() {
+ return array_map(
+ function ( $conflictDesc ) {
+ return $conflictDesc[ 'filterObject' ];
+ },
+ $this->conflictingFilters
+ );
+ }
+
+ /**
+ * 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;
+ }
+ );
+ }
+}
scripts.mit.edu / autoinstallsdev / mediawiki.git / blobdiff