ChangesListFilter.php

Go to the documentation of this file.

<?php
use MediaWiki\Context\IContextSource;
use MediaWiki\Html\FormOptions;
 
abstract class ChangesListFilter {
    protected $name;
 
    protected $cssClassSuffix;
 
    protected $isRowApplicableCallable;
 
    protected $group;
 
    protected $label;
 
    protected $description;
 
    protected $conflictingGroups = [];
 
    protected $conflictingFilters = [];
 
    protected $subsetFilters = [];
 
    protected $priority;
 
    protected $defaultHighlightColor;
 
    private const RESERVED_NAME_CHAR = '_';
 
    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 );
    }
 
    public function conflictsWith( $other, string $globalKey, string $forwardKey, string $backwardKey ) {
        $this->setUnidirectionalConflict(
            $other,
            $globalKey,
            $forwardKey
        );
 
        $other->setUnidirectionalConflict(
            $this,
            $globalKey,
            $backwardKey
        );
    }
 
    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'
            );
        }
    }
 
    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(),
        ];
    }
 
    public function getName() {
        return $this->name;
    }
 
    public function getGroup() {
        return $this->group;
    }
 
    public function getLabel() {
        return $this->label;
    }
 
    public function getDescription() {
        return $this->description;
    }
 
    abstract public function displaysOnUnstructuredUi();
 
    public function displaysOnStructuredUi() {
        return $this->label !== null;
    }
 
    public function isFeatureAvailableOnStructuredUi() {
        return $this->displaysOnStructuredUi();
    }
 
    public function getPriority() {
        return $this->priority;
    }
 
    protected function getCssClass() {
        if ( $this->cssClassSuffix !== null ) {
            return ChangesList::CSS_CLASS_PREFIX . $this->cssClassSuffix;
        } else {
            return null;
        }
    }
 
    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();
        }
    }
 
    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;
    }
 
    abstract public function isSelected( FormOptions $opts );
 
    public function getConflictingGroups() {
        return array_column( $this->conflictingGroups, 'groupObject' );
    }
 
    public function getConflictingFilters() {
        return array_column( $this->conflictingFilters, 'filterObject' );
    }
 
    public function activelyInConflictWithGroup( ChangesListFilterGroup $group, FormOptions $opts ) {
        if ( $group->anySelected( $opts ) && $this->isSelected( $opts ) ) {
            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() );
    }
 
    public function activelyInConflictWithFilter( ChangesListFilter $filter, FormOptions $opts ) {
        if ( $this->isSelected( $opts ) && $filter->isSelected( $opts ) ) {
            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() );
    }
 
    protected function getSiblings() {
        return array_filter(
            $this->getGroup()->getFilters(),
            function ( $filter ) {
                return $filter !== $this;
            }
        );
    }
 
    public function setDefaultHighlightColor( $defaultHighlightColor ) {
        $this->defaultHighlightColor = $defaultHighlightColor;
    }
}