UserGroupMembership.php

Go to the documentation of this file.

<?php
use Wikimedia\Rdbms\IDatabase;
use MediaWiki\MediaWikiServices;
 
class UserGroupMembership {
    private $userId;
 
    private $group;
 
    private $expiry;
 
    public function __construct( $userId = 0, $group = null, $expiry = null ) {
        $this->userId = (int)$userId;
        $this->group = $group; // TODO throw on invalid group?
        $this->expiry = $expiry ?: null;
    }
 
    public function getUserId() {
        return $this->userId;
    }
 
    public function getGroup() {
        return $this->group;
    }
 
    public function getExpiry() {
        return $this->expiry;
    }
 
    protected function initFromRow( $row ) {
        $this->userId = (int)$row->ug_user;
        $this->group = $row->ug_group;
        $this->expiry = $row->ug_expiry === null ?
            null :
            wfTimestamp( TS_MW, $row->ug_expiry );
    }
 
    public static function newFromRow( $row ) {
        $ugm = new self;
        $ugm->initFromRow( $row );
        return $ugm;
    }
 
    public static function selectFields() {
        return [
            'ug_user',
            'ug_group',
            'ug_expiry',
        ];
    }
 
    public function delete( IDatabase $dbw = null ) {
        if ( wfReadOnly() ) {
            return false;
        }
 
        if ( $dbw === null ) {
            $dbw = wfGetDB( DB_MASTER );
        }
 
        $dbw->delete(
            'user_groups',
            [ 'ug_user' => $this->userId, 'ug_group' => $this->group ],
            __METHOD__ );
        if ( !$dbw->affectedRows() ) {
            return false;
        }
 
        // Remember that the user was in this group
        $dbw->insert(
            'user_former_groups',
            [ 'ufg_user' => $this->userId, 'ufg_group' => $this->group ],
            __METHOD__,
            [ 'IGNORE' ] );
 
        return true;
    }
 
    public function insert( $allowUpdate = false, IDatabase $dbw = null ) {
        if ( $this->group === null ) {
            throw new UnexpectedValueException(
                'Cannot insert an uninitialized UserGroupMembership instance'
            );
        } elseif ( $this->userId <= 0 ) {
            throw new UnexpectedValueException(
                'UserGroupMembership::insert() needs a positive user ID. ' .
                'Perhaps addGroup() was called before the user was added to the database.'
            );
        }
 
        $dbw = $dbw ?: wfGetDB( DB_MASTER );
        $row = $this->getDatabaseArray( $dbw );
 
        $dbw->startAtomic( __METHOD__ );
        $dbw->insert( 'user_groups', $row, __METHOD__, [ 'IGNORE' ] );
        $affected = $dbw->affectedRows();
        if ( !$affected ) {
            // Conflicting row already exists; it should be overriden if it is either expired
            // or if $allowUpdate is true and the current row is different than the loaded row.
            $conds = [ 'ug_user' => $row['ug_user'], 'ug_group' => $row['ug_group'] ];
            if ( $allowUpdate ) {
                // Update the current row if its expiry does not match that of the loaded row
                $conds[] = $this->expiry
                    ? 'ug_expiry IS NULL OR ug_expiry != ' .
                        $dbw->addQuotes( $dbw->timestamp( $this->expiry ) )
                    : 'ug_expiry IS NOT NULL';
            } else {
                // Update the current row if it is expired
                $conds[] = 'ug_expiry < ' . $dbw->addQuotes( $dbw->timestamp() );
            }
            $dbw->update(
                'user_groups',
                [ 'ug_expiry' => $this->expiry ? $dbw->timestamp( $this->expiry ) : null ],
                $conds,
                __METHOD__
            );
            $affected = $dbw->affectedRows();
        }
        $dbw->endAtomic( __METHOD__ );
 
        // Purge old, expired memberships from the DB
        $fname = __METHOD__;
        DeferredUpdates::addCallableUpdate( function () use ( $dbw, $fname ) {
            $hasExpiredRow = $dbw->selectField(
                'user_groups',
                '1',
                [ 'ug_expiry < ' . $dbw->addQuotes( $dbw->timestamp() ) ],
                $fname
            );
            if ( $hasExpiredRow ) {
                JobQueueGroup::singleton()->push( new UserGroupExpiryJob() );
            }
        } );
 
        return $affected > 0;
    }
 
    protected function getDatabaseArray( IDatabase $db ) {
        return [
            'ug_user' => $this->userId,
            'ug_group' => $this->group,
            'ug_expiry' => $this->expiry ? $db->timestamp( $this->expiry ) : null,
        ];
    }
 
    public function isExpired() {
        if ( !$this->expiry ) {
            return false;
        }
        return wfTimestampNow() > $this->expiry;
    }
 
    public static function purgeExpired() {
        $services = MediaWikiServices::getInstance();
        if ( $services->getReadOnlyMode()->isReadOnly() ) {
            return false;
        }
 
        $lbFactory = $services->getDBLoadBalancerFactory();
        $ticket = $lbFactory->getEmptyTransactionTicket( __METHOD__ );
        $dbw = $services->getDBLoadBalancer()->getConnectionRef( DB_MASTER );
 
        $lockKey = "{$dbw->getDomainID()}:UserGroupMembership:purge"; // per-wiki
        $scopedLock = $dbw->getScopedLockAndFlush( $lockKey, __METHOD__, 0 );
        if ( !$scopedLock ) {
            return false; // already running
        }
 
        $now = time();
        $purgedRows = 0;
        do {
            $dbw->startAtomic( __METHOD__ );
 
            $res = $dbw->select(
                'user_groups',
                self::selectFields(),
                [ 'ug_expiry < ' . $dbw->addQuotes( $dbw->timestamp( $now ) ) ],
                __METHOD__,
                [ 'FOR UPDATE', 'LIMIT' => 100 ]
            );
 
            if ( $res->numRows() > 0 ) {
                $insertData = []; // array of users/groups to insert to user_former_groups
                $deleteCond = []; // array for deleting the rows that are to be moved around
                foreach ( $res as $row ) {
                    $insertData[] = [ 'ufg_user' => $row->ug_user, 'ufg_group' => $row->ug_group ];
                    $deleteCond[] = $dbw->makeList(
                        [ 'ug_user' => $row->ug_user, 'ug_group' => $row->ug_group ],
                        $dbw::LIST_AND
                    );
                }
                // Delete the rows we're about to move
                $dbw->delete(
                    'user_groups',
                    $dbw->makeList( $deleteCond, $dbw::LIST_OR ),
                    __METHOD__
                );
                // Push the groups to user_former_groups
                $dbw->insert( 'user_former_groups', $insertData, __METHOD__, [ 'IGNORE' ] );
                // Count how many rows were purged
                $purgedRows += $res->numRows();
            }
 
            $dbw->endAtomic( __METHOD__ );
 
            $lbFactory->commitAndWaitForReplication( __METHOD__, $ticket );
        } while ( $res->numRows() > 0 );
        return $purgedRows;
    }
 
    public static function getMembershipsForUser( $userId, IDatabase $db = null ) {
        if ( !$db ) {
            $db = wfGetDB( DB_REPLICA );
        }
 
        $res = $db->select( 'user_groups',
            self::selectFields(),
            [ 'ug_user' => $userId ],
            __METHOD__ );
 
        $ugms = [];
        foreach ( $res as $row ) {
            $ugm = self::newFromRow( $row );
            if ( !$ugm->isExpired() ) {
                $ugms[$ugm->group] = $ugm;
            }
        }
        ksort( $ugms );
 
        return $ugms;
    }
 
    public static function getMembership( $userId, $group, IDatabase $db = null ) {
        if ( !$db ) {
            $db = wfGetDB( DB_REPLICA );
        }
 
        $row = $db->selectRow( 'user_groups',
            self::selectFields(),
            [ 'ug_user' => $userId, 'ug_group' => $group ],
            __METHOD__ );
        if ( !$row ) {
            return false;
        }
 
        $ugm = self::newFromRow( $row );
        if ( !$ugm->isExpired() ) {
            return $ugm;
        }
        return false;
    }
 
    public static function getLink( $ugm, IContextSource $context, $format,
        $userName = null
    ) {
        if ( $format !== 'wiki' && $format !== 'html' ) {
            throw new MWException( 'UserGroupMembership::getLink() $format parameter should be ' .
                "'wiki' or 'html'" );
        }
 
        if ( $ugm instanceof UserGroupMembership ) {
            $expiry = $ugm->getExpiry();
            $group = $ugm->getGroup();
        } else {
            $expiry = null;
            $group = $ugm;
        }
 
        if ( $userName !== null ) {
            $groupName = self::getGroupMemberName( $group, $userName );
        } else {
            $groupName = self::getGroupName( $group );
        }
 
        // link to the group description page, if it exists
        $linkTitle = self::getGroupPage( $group );
        $linkRenderer = MediaWikiServices::getInstance()->getLinkRenderer();
        if ( $format === 'wiki' ) {
            if ( $linkTitle ) {
                $linkPage = $linkTitle->getFullText();
                $groupLink = "[[$linkPage|$groupName]]";
            } else {
                $groupLink = $groupName;
            }
        } else {
            if ( $linkTitle ) {
                $groupLink = $linkRenderer->makeLink( $linkTitle, $groupName );
            } else {
                $groupLink = htmlspecialchars( $groupName );
            }
        }
 
        if ( $expiry ) {
            // format the expiry to a nice string
            $uiLanguage = $context->getLanguage();
            $uiUser = $context->getUser();
            $expiryDT = $uiLanguage->userTimeAndDate( $expiry, $uiUser );
            $expiryD = $uiLanguage->userDate( $expiry, $uiUser );
            $expiryT = $uiLanguage->userTime( $expiry, $uiUser );
 
            if ( $format === 'wiki' ) {
                return $context->msg( 'group-membership-link-with-expiry' )
                    ->params( $groupLink, $expiryDT, $expiryD, $expiryT )->text();
            } else {
                $groupLink = Message::rawParam( $groupLink );
                return $context->msg( 'group-membership-link-with-expiry' )
                    ->params( $groupLink, $expiryDT, $expiryD, $expiryT )->escaped();
            }
        }
        return $groupLink;
    }
 
    public static function getGroupName( $group ) {
        $msg = wfMessage( "group-$group" );
        return $msg->isBlank() ? $group : $msg->text();
    }
 
    public static function getGroupMemberName( $group, $username ) {
        $msg = wfMessage( "group-$group-member", $username );
        return $msg->isBlank() ? $group : $msg->text();
    }
 
    public static function getGroupPage( $group ) {
        $msg = wfMessage( "grouppage-$group" )->inContentLanguage();
        if ( $msg->exists() ) {
            $title = Title::newFromText( $msg->text() );
            if ( is_object( $title ) ) {
                return $title;
            }
        }
        return false;
    }
}