ChangesListFilterGroup.php

Go to the documentation of this file.

<?php
// TODO: Might want to make a super-class or trait to share behavior (especially re
// conflicts) between ChangesListFilter and ChangesListFilterGroup.
// What to call it.  FilterStructure?  That would also let me make
// setUnidirectionalConflict protected.
 
use MediaWiki\Html\FormOptions;
use MediaWiki\SpecialPage\ChangesListSpecialPage;
use Wikimedia\Rdbms\IReadableDatabase;
 
abstract class ChangesListFilterGroup {
    protected $name;
 
    protected $title;
 
    protected $whatsThisHeader;
 
    protected $whatsThisBody;
 
    protected $whatsThisUrl;
 
    protected $whatsThisLinkText;
 
    protected $type;
 
    protected $priority;
 
    protected $filters;
 
    protected $isFullCoverage;
 
    protected $conflictingGroups = [];
 
    protected $conflictingFilters = [];
 
    private const DEFAULT_PRIORITY = -100;
 
    private const RESERVED_NAME_CHAR = '_';
 
    public function __construct( array $groupDefinition ) {
        if ( strpos( $groupDefinition['name'], self::RESERVED_NAME_CHAR ) !== false ) {
            throw new InvalidArgumentException( 'Group names may not contain \'' .
                self::RESERVED_NAME_CHAR .
                '\'.  Use the naming convention: \'camelCase\''
            );
        }
 
        $this->name = $groupDefinition['name'];
 
        if ( isset( $groupDefinition['title'] ) ) {
            $this->title = $groupDefinition['title'];
        }
 
        if ( isset( $groupDefinition['whatsThisHeader'] ) ) {
            $this->whatsThisHeader = $groupDefinition['whatsThisHeader'];
            $this->whatsThisBody = $groupDefinition['whatsThisBody'];
            $this->whatsThisUrl = $groupDefinition['whatsThisUrl'];
            $this->whatsThisLinkText = $groupDefinition['whatsThisLinkText'];
        }
 
        $this->type = $groupDefinition['type'];
        $this->priority = $groupDefinition['priority'] ?? self::DEFAULT_PRIORITY;
 
        $this->isFullCoverage = $groupDefinition['isFullCoverage'];
 
        $this->filters = [];
        $lowestSpecifiedPriority = -1;
        foreach ( $groupDefinition['filters'] as $filterDefinition ) {
            if ( isset( $filterDefinition['priority'] ) ) {
                $lowestSpecifiedPriority = min( $lowestSpecifiedPriority, $filterDefinition['priority'] );
            }
        }
 
        // Convenience feature: If you specify a group (and its filters) all in
        // one place, you don't have to specify priority.  You can just put them
        // in order.  However, if you later add one (e.g. an extension adds a filter
        // to a core-defined group), you need to specify it.
        $autoFillPriority = $lowestSpecifiedPriority - 1;
        foreach ( $groupDefinition['filters'] as $filterDefinition ) {
            if ( !isset( $filterDefinition['priority'] ) ) {
                $filterDefinition['priority'] = $autoFillPriority;
                $autoFillPriority--;
            }
            $filterDefinition['group'] = $this;
 
            $filter = $this->createFilter( $filterDefinition );
            $this->registerFilter( $filter );
        }
    }
 
    abstract protected function createFilter( array $filterDefinition );
 
    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 getName() {
        return $this->name;
    }
 
    public function getTitle() {
        return $this->title;
    }
 
    public function getType() {
        return $this->type;
    }
 
    public function getPriority() {
        return $this->priority;
    }
 
    public function getFilters() {
        return $this->filters;
    }
 
    public function getFilter( $name ) {
        return $this->filters[$name] ?? null;
    }
 
    public function getJsData() {
        $output = [
            'name' => $this->name,
            'type' => $this->type,
            'fullCoverage' => $this->isFullCoverage,
            'filters' => [],
            'priority' => $this->priority,
            'conflicts' => [],
            'messageKeys' => [ $this->title ]
        ];
 
        if ( isset( $this->whatsThisHeader ) ) {
            $output['whatsThisHeader'] = $this->whatsThisHeader;
            $output['whatsThisBody'] = $this->whatsThisBody;
            $output['whatsThisUrl'] = $this->whatsThisUrl;
            $output['whatsThisLinkText'] = $this->whatsThisLinkText;
 
            array_push(
                $output['messageKeys'],
                $output['whatsThisHeader'],
                $output['whatsThisBody'],
                $output['whatsThisLinkText']
            );
        }
 
        usort( $this->filters, static function ( ChangesListFilter $a, ChangesListFilter $b ) {
            return $b->getPriority() <=> $a->getPriority();
        } );
 
        foreach ( $this->filters as $filter ) {
            if ( $filter->displaysOnStructuredUi() ) {
                $filterData = $filter->getJsData();
                $output['messageKeys'] = array_merge(
                    $output['messageKeys'],
                    $filterData['messageKeys']
                );
                unset( $filterData['messageKeys'] );
                $output['filters'][] = $filterData;
            }
        }
 
        if ( count( $output['filters'] ) === 0 ) {
            return null;
        }
 
        $output['title'] = $this->title;
 
        $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;
    }
 
    public function getConflictingGroups() {
        return array_column( $this->conflictingGroups, 'groupObject' );
    }
 
    public function getConflictingFilters() {
        return array_column( $this->conflictingFilters, 'filterObject' );
    }
 
    public function anySelected( FormOptions $opts ) {
        return (bool)count( array_filter(
            $this->getFilters(),
            static function ( ChangesListFilter $filter ) use ( $opts ) {
                return $filter->isSelected( $opts );
            }
        ) );
    }
 
    abstract public function modifyQuery( IReadableDatabase $dbr, ChangesListSpecialPage $specialPage,
        &$tables, &$fields, &$conds, &$query_options, &$join_conds,
        FormOptions $opts, $isStructuredFiltersEnabled );
 
    abstract public function addOptions( FormOptions $opts, $allowDefaults,
        $isStructuredFiltersEnabled );
}