UserGroupsSpecialPage.php

Go to the documentation of this file.

<?php
namespace MediaWiki\SpecialPage;
 
use MediaWiki\CommentStore\CommentStore;
use MediaWiki\Html\Html;
use MediaWiki\HTMLForm\HTMLForm;
use MediaWiki\Logging\LogEventsList;
use MediaWiki\Logging\LogPage;
use MediaWiki\Message\Message;
use MediaWiki\Title\Title;
use MediaWiki\User\UserGroupAssignmentService;
use MediaWiki\User\UserGroupMembership;
use MediaWiki\Xml\XmlSelect;
use OOUI\FieldLayout;
use OOUI\FieldsetLayout;
use OOUI\HtmlSnippet;
use OOUI\LabelWidget;
use OOUI\PanelLayout;
use Status;
 
abstract class UserGroupsSpecialPage extends SpecialPage {
 
    protected string $targetBareName = '';
 
    protected string $targetDisplayName = '';
 
    protected array $explicitGroups = [];
 
    protected array $groupMemberships = [];
 
    protected array $addableGroups = [];
 
    protected array $removableGroups = [];
 
    protected array $groupAnnotations = [];
 
    protected bool $enableWatchUser = true;
 
    private const SAVE_SUCCESS_FLAG = 'specialUserrightsSaveSuccess';
 
    private const CONFLICT_CHECK_FIELD = 'conflictcheck-originalgroups';
 
    protected function setTargetName( string $bareName, ?string $displayName = null ): void {
        $this->targetBareName = $bareName;
        $this->targetDisplayName = $displayName ?? $bareName;
    }
 
    protected function setChangeableGroups( array $changeableGroups ): void {
        $this->addableGroups = $changeableGroups['add'];
        $this->removableGroups = $changeableGroups['remove'];
        foreach ( $changeableGroups['restricted'] as $group => $details ) {
            $isConditionMet = $details['condition-met'];
            if ( $isConditionMet === false ) {
                if ( isset( $details['message'] ) ) {
                    $messageKey = $details['message'];
                } else {
                    $customMessageKey = 'userrights-restricted-group-' . $group;
                    $messageKey = $this->msg( $customMessageKey )->exists() ?
                        $customMessageKey :
                        'userrights-restricted-group-warning';
                }
                $this->addGroupAnnotation( $group, $messageKey );
            } elseif ( $isConditionMet === null ) {
                $customMessageKey = 'userrights-restricted-group-' . $group . '-private-conditions';
                $messageKey = $this->msg( $customMessageKey )->exists() ?
                    $customMessageKey :
                    'userrights-restricted-group-warning-private-conditions';
                $this->addGroupAnnotation( $group, $messageKey );
            }
        }
    }
 
    protected function addModules(): void {
        $out = $this->getOutput();
        $out->addModules( [ 'mediawiki.special.userrights' ] );
        $out->addModuleStyles( [ 'mediawiki.special', 'mediawiki.codex.messagebox.styles' ] );
    }
 
    protected function showMessageOnSuccess(): void {
        $session = $this->getRequest()->getSession();
        if ( $session->get( self::SAVE_SUCCESS_FLAG ) ) {
            // Remove session data for the success message
            $session->remove( self::SAVE_SUCCESS_FLAG );
 
            $out = $this->getOutput();
            $out->addModuleStyles( 'mediawiki.notification.convertmessagebox.styles' );
            $out->addHTML(
                Html::successBox(
                    Html::element(
                        'p',
                        [],
                        $this->msg( 'savedrights', $this->targetDisplayName )->text()
                    ),
                    'mw-notify-success'
                )
            );
        }
    }
 
    protected function setSuccessFlag(): void {
        $session = $this->getRequest()->getSession();
        $session->set( self::SAVE_SUCCESS_FLAG, 1 );
    }
 
    protected function buildGroupsForm(): string {
        $this->getOutput()->addBodyClasses( 'mw-special-UserGroupsSpecialPage' );
 
        $groups = $this->prepareAvailableGroups();
 
        $canChangeAny = array_any(
            $groups,
            static fn ( $group ) => $group['canAdd'] || $group['canRemove']
        );
 
        $panel = $canChangeAny ?
            $this->buildEditGroupsFormContent( $groups ) :
            $this->buildViewGroupsFormContent();
        return $panel->toString();
    }
 
    private function buildFormHeader( string $messageKey ): string {
        return $this->msg( $messageKey, $this->targetBareName )->text();
    }
 
    private function buildFormDescription( string $messageKey ): string {
        return $this->msg( $messageKey )
            ->params( wfEscapeWikiText( $this->targetDisplayName ) )
            ->rawParams( $this->getTargetUserToolLinks() )->parse();
    }
 
    private function buildFormGroupsLists(): array {
        return array_map( static function ( $field ) {
            return $field['label'] . ' ' . $field['list'];
        }, $this->getCurrentUserGroupsFields() );
    }
 
    protected function buildFormExtraInfo(): ?string {
        return null;
    }
 
    private function buildViewGroupsFormContent(): PanelLayout {
        $panelLabel = $this->buildFormHeader( 'userrights-viewusergroup' );
 
        $panelItems = array_filter( [
            $this->buildFormDescription( 'viewinguserrights' ),
            ...$this->buildFormGroupsLists(),
            $this->buildFormExtraInfo(),
        ] );
        $panelItems = array_map( static function ( $label ) {
            return new FieldLayout(
                new LabelWidget( [
                    'label' => new HtmlSnippet( $label )
                ] )
            );
        }, $panelItems );
 
        return new PanelLayout( [
            'expanded' => false,
            'padded' => true,
            'framed' => true,
            'content' => new FieldsetLayout( [
                'label' => $panelLabel,
                'items' => $panelItems,
            ] )
        ] );
    }
 
    private function buildEditGroupsFormContent( array $groups ): PanelLayout {
        $panelLabel = $this->buildFormHeader( 'userrights-editusergroup' );
 
        $panelItems = array_filter( [
            $this->buildFormDescription( 'editinguser' ),
            $this->msg( 'userrights-groups-help', $this->targetBareName )->parse(),
            ...$this->buildFormGroupsLists(),
            $this->buildFormExtraInfo(),
        ] );
        $panelItems = array_map( static function ( $label ) {
            return new FieldLayout(
                new LabelWidget( [
                    'label' => new HtmlSnippet( $label )
                ] )
            );
        }, $panelItems );
 
        $formDescriptor = [
            'user' => [
                'type' => 'hidden',
                'name' => 'user',
                'default' => $this->targetDisplayName,
            ],
            'EditToken' => [
                'type' => 'hidden',
                'default' => $this->getUser()->getEditToken( $this->targetDisplayName ),
            ],
            self::CONFLICT_CHECK_FIELD => [
                'type' => 'hidden',
                'name' => self::CONFLICT_CHECK_FIELD,
                'default' => $this->makeConflictCheckKey(),
            ],
        ];
 
        $memberships = $this->groupMemberships;
        $unchangeableGroupFields = [];
        $changeableGroupFields = [];
        foreach ( $groups as $group => $groupData ) {
            $isMember = array_key_exists( $group, $memberships );
            $expiry = null;
            if ( $isMember ) {
                $expiry = $memberships[$group]->getExpiry();
            }
 
            [ $groupFields, $isChangeable ] = $this->makeGroupFields(
                $groupData,
                $isMember,
                $expiry,
                $this->targetBareName
            );
 
            if ( $isChangeable ) {
                $changeableGroupFields += $groupFields;
            } else {
                $unchangeableGroupFields += $groupFields;
            }
        }
 
        // Ensure that the unchangeable fields section is before the changeable fields section,
        // so that it displays on the correct side, if present.
        $formDescriptor += $unchangeableGroupFields;
        $formDescriptor += $changeableGroupFields;
 
        $formDescriptor['user-reason'] = [
            'type' => 'text',
            'name' => 'user-reason',
            'id' => 'wpReason',
            'label' => $this->msg( 'userrights-reason' )->text(),
            // HTML maxlength uses "UTF-16 code units", which means that characters outside BMP
            // (e.g. emojis) count for two each. This limit is overridden in JS to instead count
            // Unicode codepoints.
            'maxlength' => CommentStore::COMMENT_CHARACTER_LIMIT,
            'maxlength-unit' => 'codepoints',
            'size' => 60,
            'default' => $this->getRequest()->getVal( 'user-reason' ) ?? false,
        ];
 
        if ( $this->enableWatchUser ) {
            $formDescriptor['Watch'] = [
                'type' => 'check',
                'default' => false,
                'id' => 'wpWatch',
                'label' => $this->msg( 'userrights-watchuser' )->text(),
            ];
        }
 
        $htmlForm = HTMLForm::factory( 'ooui', $formDescriptor, $this->getContext(), 'userrights' );
        $htmlForm
            ->setMethod( 'POST' )
            ->setName( 'editGroup' )
            ->setTitle( $this->getPageTitle() )
            ->setId( 'mw-userrights-form2' )
            ->setSubmitTextMsg( $this->msg( 'saveusergroups', $this->targetBareName ) )
            ->setSubmitName( 'saveusergroups' )
            ->prepareForm();
        $form = $htmlForm->getHtml( true );
 
        return new PanelLayout( [
            'expanded' => false,
            'padded' => true,
            'framed' => true,
            'content' => [
                new FieldsetLayout( [
                    'label' => $panelLabel,
                    'items' => $panelItems,
                ] ),
                new PanelLayout( [
                    'expanded' => false,
                    'content' => new HtmlSnippet( $form ),
                ] )
            ],
        ] );
    }
 
    private function prepareAvailableGroups(): array {
        $allGroups = $this->explicitGroups;
 
        // We store user groups with information whether the current user can add/remove them
        // and possibly other data that will be then used for rendering the form
        $result = [];
 
        foreach ( $allGroups as $group ) {
            $result[$group] = [
                'group' => $group,
                'canAdd' => $this->canAdd( $group ),
                'canRemove' => $this->canRemove( $group ),
                'annotations' => $this->getGroupAnnotations( $group ),
            ];
        }
 
        return $result;
    }
 
    private function makeGroupFields( array $groupData, bool $isMember, ?string $expiry, string $userName ): array {
        $group = $groupData['group'];
        $uiLanguage = $this->getLanguage();
        $member = $uiLanguage->getGroupMemberName( $group, $userName );
 
        // Users who can add the group, but not remove it, can only lengthen
        // expiries, not shorten them. So they should only see the expiry
        // dropdown if the group currently has a finite expiry
        $canOnlyLengthenExpiry = (
            $isMember && $expiry &&
            $groupData['canAdd'] && !$groupData['canRemove']
        );
 
        // Should the checkbox be disabled?
        $disabledCheckbox = !(
            ( $isMember && $groupData['canRemove'] ) ||
            ( !$isMember && $groupData['canAdd'] )
        );
 
        // Should the expiry elements be disabled?
        $disabledExpiry = $disabledCheckbox && !$canOnlyLengthenExpiry;
 
        // Do we need to point out that this action is irreversible?
        $irreversible = !$disabledCheckbox && (
            ( $isMember && !$groupData['canAdd'] ) ||
            ( !$isMember && !$groupData['canRemove'] )
        );
 
        if ( $irreversible ) {
            $text = $this->msg( 'userrights-irreversible-marker', $member )->text();
        } elseif ( $disabledCheckbox && !$disabledExpiry ) {
            $text = $this->msg( 'userrights-no-shorten-expiry-marker', $member )->text();
        } else {
            $text = $member;
        }
 
        $checkboxField = [
            'type' => 'check',
            'name' => "wpGroup-$group",
            'id' => "wpGroup-$group",
            'default' => $isMember,
            'cssclass' => 'mw-userrights-groupcheckbox',
            'disabled' => $disabledCheckbox,
            'label' => $text,
            'help-messages' => [],
        ];
 
        foreach ( $groupData['annotations'] as $annotation ) {
            if ( !$annotation instanceof Message ) {
                $message = $this->msg( $annotation );
            } else {
                $message = $annotation;
            }
 
            $checkboxField['help-messages'][] = $message;
            $checkboxField['help-messages'][] = $this->msg( 'userrights-checkbox-help-message-separator' );
        }
 
        $uiUser = $this->getUser();
 
        // If the user can't modify the expiry, print the current expiry below
        // it in plain text. Otherwise, provide UI to set/change the expiry
        if ( $isMember && ( $irreversible || $disabledExpiry ) ) {
            if ( $expiry ) {
                $checkboxField['help-messages'][] = $this->msg( 'userrights-expiry-current' )->params(
                    $uiLanguage->userTimeAndDate( $expiry, $uiUser ),
                    $uiLanguage->userDate( $expiry, $uiUser ),
                    $uiLanguage->userTime( $expiry, $uiUser )
                );
            } else {
                $checkboxField['help-messages'][] = $this->msg( 'userrights-expiry-none' );
            }
            // T171345: Add a hidden form element so that other groups can still be manipulated,
            // otherwise saving errors out with an invalid expiry time for this group.
            $expiryField = [
                'type' => 'hidden',
                'name' => "wpExpiry-$group",
                'default' => $expiry ? 'existing' : 'infinite',
            ];
        } else {
            $expiryField = [
                'type' => 'selectorother',
                'label' => $this->msg( 'userrights-expiry-for', $member )->text(),
                'other-message' => 'userrights-expiry-othertime',
                'name' => "wpExpiry-$group",
                'id' => "mw-input-wpExpiry-$group",
                'hide-if' => [ '!==', "wpGroup-$group", '1' ],
                'disabled' => $disabledExpiry,
            ];
 
            // Create expiry field options. If there is an existing expiry, set it to the default.
            // Otherwise, default to infinite.
            $expiries = [];
 
            $expiries[$this->msg( 'userrights-expiry-none' )->text()] = 'infinite';
            $expiryOptionsMsg = $this->msg( 'userrights-expiry-options' )->inContentLanguage();
            $expiryOptions = $expiryOptionsMsg->isDisabled()
                ? []
                : XmlSelect::parseOptionsMessage( $expiryOptionsMsg->text() );
            $expiries = array_merge( $expiries, $expiryOptions );
 
            if ( $isMember && $expiry ) {
                $existingExpiryText = $this->msg(
                    'userrights-expiry-existing',
                    $uiLanguage->userTimeAndDate( $expiry, $uiUser ),
                    $uiLanguage->userDate( $expiry, $uiUser ),
                    $uiLanguage->userTime( $expiry, $uiUser )
                )->text();
                $expiries[$existingExpiryText] = 'existing';
                $expiryField['default'] = 'existing';
            } else {
                $expiryField['default'] = 'infinite';
            }
 
            $expiryField['options'] = $expiries;
        }
 
        $fullyDisabled = $disabledCheckbox && $disabledExpiry;
        $checkboxField['section'] = $fullyDisabled ? 'unchangeable-col' : 'changeable-col';
        $expiryField['section'] = $fullyDisabled ? 'unchangeable-col' : 'changeable-col';
 
        $groupFields = [
            "wpGroup-$group" => $checkboxField,
            "wpExpiry-$group" => $expiryField
        ];
 
        if ( $isMember && $disabledCheckbox && !( $irreversible || $disabledExpiry ) ) {
            // If the user group is set but the checkbox is disabled, mimic a
            // checked checkbox in the form submission so that the expiry is read
            $groupFields["wpHidden-$group"] = [
                'type' => 'hidden',
                'name' => "wpGroup-$group",
                'default' => 1,
            ];
        }
 
        return [ $groupFields, !$fullyDisabled ];
    }
 
    protected function readGroupsForm(): Status {
        $allGroups = $this->explicitGroups;
        // New state of the user groups, read from the form (group name => expiry)
        // The expiry is either timestamp, null or 'existing' (meaning no change)
        $newGroups = [];
 
        foreach ( $allGroups as $group ) {
            // We'll tell it to remove all unchecked groups, and add all checked groups.
            // For disabled checkboxes, the state is propagated from the current memberships.
            if ( $this->getRequest()->getCheck( "wpGroup-$group" ) ) {
                // Default expiry is infinity, may be changed below
                $newGroups[$group] = null;
 
                // read the expiry information from the request
                $expiryDropdown = $this->getRequest()->getVal( "wpExpiry-$group" );
                if ( $expiryDropdown === 'existing' ) {
                    $newGroups[$group] = 'existing';
                    continue;
                }
 
                if ( $expiryDropdown === 'other' ) {
                    $expiryValue = $this->getRequest()->getVal( "wpExpiry-$group-other" );
                } else {
                    $expiryValue = $expiryDropdown;
                }
 
                // validate the expiry
                $expiry = UserGroupAssignmentService::expiryToTimestamp( $expiryValue );
 
                if ( $expiry === false ) {
                    return Status::newFatal( 'userrights-invalid-expiry', $group );
                }
 
                // not allowed to have things expiring in the past
                if ( $expiry && $expiry < wfTimestampNow() ) {
                    return Status::newFatal( 'userrights-expiry-in-past', $group );
                }
 
                $newGroups[$group] = $expiry;
            } elseif ( !$this->canRemove( $group ) && isset( $this->groupMemberships[$group] ) ) {
                // If the checkbox is absent from the request, it's either unchecked or disabled.
                // If it's the latter, pretend that its state hasn't changed from the current group membership.
                $newGroups[$group] = 'existing';
            }
        }
 
        return Status::newGood( $newGroups );
    }
 
    protected function splitGroupsIntoAddRemove( array $newGroups, array $existingUGMs ): array {
        $involvedGroups = array_unique( array_merge( array_keys( $existingUGMs ), array_keys( $newGroups ) ) );
 
        $addGroups = [];
        $removeGroups = [];
        $groupExpiries = [];
        foreach ( $involvedGroups as $group ) {
            // By definition of $involvedGroups, at least one of $hasGroup and $wantsGroup is true
            $hasGroup = array_key_exists( $group, $existingUGMs );
            $wantsGroup = array_key_exists( $group, $newGroups );
 
            if ( $wantsGroup && $newGroups[$group] === 'existing' ) {
                // No change requested for this group
                continue;
            }
 
            if ( $hasGroup && !$wantsGroup ) {
                $removeGroups[] = $group;
                continue;
            }
            if ( !$hasGroup && $wantsGroup ) {
                $addGroups[] = $group;
                $groupExpiries[$group] = $newGroups[$group];
                continue;
            }
 
            $currentExpiry = $existingUGMs[$group]->getExpiry();
            $wantedExpiry = $newGroups[$group];
            if ( $currentExpiry !== $wantedExpiry ) {
                $addGroups[] = $group;
                $groupExpiries[$group] = $wantedExpiry;
            }
        }
 
        return [ $addGroups, $removeGroups, $groupExpiries ];
    }
 
    private function getCurrentUserGroupsFields(): array {
        $userGroups = $this->sortGroupMemberships( $this->groupMemberships );
        $groupParagraphs = $this->categorizeUserGroupsForDisplay( $userGroups );
 
        $context = $this->getContext();
        $userName = $this->targetBareName;
        $language = $this->getLanguage();
 
        $fields = [];
        foreach ( $groupParagraphs as $paragraphKey => $groups ) {
            if ( count( $groups ) === 0 ) {
                continue;
            }
 
            $groupLinks = array_map(
                static fn ( $group ) => UserGroupMembership::getLinkHTML( $group, $context ),
                $groups
            );
            $memberLinks = array_map(
                static fn ( $group ) => UserGroupMembership::getLinkHTML( $group, $context, $userName ),
                $groups
            );
 
            // Some languages prefer to have group names listed and some others prefer the member names,
            // i.e. "Administrators" or "Administrator", respectively. This message acts as a switch between these.
            $displayedList = $this->msg( 'userrights-groupsmember-type' )
                ->rawParams(
                    $language->commaList( $groupLinks ),
                    $language->commaList( $memberLinks )
                )->escaped();
 
            $paragraphHeader = $this->msg( $paragraphKey )
                ->numParams( count( $groups ) )
                ->params( $userName )
                ->parse();
 
            $fields[] = [
                'label' => $paragraphHeader,
                'list' => $displayedList
            ];
        }
        return $fields;
    }
 
    protected function showLogFragment( string $logType, string $logSubType ): void {
        $logPage = new LogPage( $logType );
 
        $logTitle = $logPage->getName()
            // setContext allows us to test it - otherwise, English text would be used in tests
            ->setContext( $this->getContext() )
            ->text();
 
        $output = $this->getOutput();
        $output->addHTML( Html::element( 'h2', [], $logTitle ) );
        LogEventsList::showLogExtract(
            $output,
            $logSubType,
            Title::makeTitle( NS_USER, $this->targetDisplayName )
        );
    }
 
    protected function categorizeUserGroupsForDisplay( array $userGroups ): array {
        return [
            'userrights-groupsmember' => array_values( $userGroups ),
        ];
    }
 
    protected function makeConflictCheckKey( ?array $groupMemberships = null ): string {
        $groupMemberships ??= $this->groupMemberships;
        $groups = array_keys( $groupMemberships );
        // Sort, so that the keys are safe to compare
        sort( $groups );
        return implode( ',', $groups );
    }
 
    protected function conflictOccured( ?array $groupMembershipsPrimary = null ): bool {
        $request = $this->getRequest();
        $receivedConflictCheck = $request->getVal( self::CONFLICT_CHECK_FIELD );
        $expectedConflictCheck = $this->makeConflictCheckKey( $groupMembershipsPrimary );
 
        return $receivedConflictCheck !== $expectedConflictCheck;
    }
 
    abstract protected function getTargetUserToolLinks(): string;
 
    protected function canAdd( string $group ): bool {
        return in_array( $group, $this->addableGroups );
    }
 
    protected function canRemove( string $group ): bool {
        return in_array( $group, $this->removableGroups );
    }
 
    protected function getGroupAnnotations( string $group ): array {
        return $this->groupAnnotations[$group] ?? [];
    }
 
    protected function addGroupAnnotation( string $group, Message|string $annotation ): void {
        $this->groupAnnotations[$group][] = $annotation;
    }
 
    private function sortGroupMemberships( array $memberships ): array {
        uasort( $memberships, static function ( $a, $b ) {
            $aPermanent = $a->getExpiry() === null;
            $bPermanent = $b->getExpiry() === null;
 
            if ( $aPermanent === $bPermanent ) {
                return $a->getGroup() <=> $b->getGroup();
            } else {
                return $aPermanent ? 1 : -1;
            }
        } );
        return $memberships;
    }
 
    public function doesWrites() {
        return true;
    }
 
    protected function getGroupName() {
        return 'users';
    }
}