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 ( $dbw === null ) {
            $dbw = wfGetDB( DB_MASTER );
        }

        // Purge old, expired memberships from the DB
        JobQueueGroup::singleton()->push( new UserGroupExpiryJob() );

        // Check that the values make sense
        if ( $this->group === null ) {
            throw new UnexpectedValueException(
                'Don\'t try inserting an uninitialized UserGroupMembership object' );
        } elseif ( $this->userId <= 0 ) {
            throw new UnexpectedValueException(
                'UserGroupMembership::insert() needs a positive user ID. ' .
                'Did you forget to add your User object to the database before calling addGroup()?' );
        }

        $row = $this->getDatabaseArray( $dbw );
        $dbw->insert( 'user_groups', $row, __METHOD__, [ 'IGNORE' ] );
        $affected = $dbw->affectedRows();

        // Don't collide with expired user group memberships
        // Do this after trying to insert, in order to avoid locking
        if ( !$affected ) {
            $conds = [
                'ug_user' => $row['ug_user'],
                'ug_group' => $row['ug_group'],
            ];
            // if we're unconditionally updating, check that the expiry is not already the
            // same as what we are trying to update it to; otherwise, only update if
            // the expiry date is in the past
            if ( $allowUpdate ) {
                if ( $this->expiry ) {
                    $conds[] = 'ug_expiry IS NULL OR ug_expiry != ' .
                        $dbw->addQuotes( $dbw->timestamp( $this->expiry ) );
                } else {
                    $conds[] = 'ug_expiry IS NOT NULL';
                }
            } else {
                $conds[] = 'ug_expiry < ' . $dbw->addQuotes( $dbw->timestamp() );
            }

            $row = $dbw->selectRow( 'user_groups', $this::selectFields(), $conds, __METHOD__ );
            if ( $row ) {
                $dbw->update(
                    'user_groups',
                    [ 'ug_expiry' => $this->expiry ? $dbw->timestamp( $this->expiry ) : null ],
                    [ 'ug_user' => $row->ug_user, 'ug_group' => $row->ug_group ],
                    __METHOD__ );
                $affected = $dbw->affectedRows();
            }
        }

        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()->getConnection( DB_MASTER );

        $lockKey = $dbw->getDomainID() . ':usergroups-prune'; // specific to this 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 );
        if ( $linkTitle ) {
            if ( $format === 'wiki' ) {
                $linkPage = $linkTitle->getFullText();
                $groupLink = "[[$linkPage|$groupName]]";
            } else {
                $groupLink = Linker::link( $linkTitle, htmlspecialchars( $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 === 'html' ) {
                $groupLink = Message::rawParam( $groupLink );
            }
            return $context->msg( 'group-membership-link-with-expiry' )
                ->params( $groupLink, $expiryDT, $expiryD, $expiryT )->text();
        }
        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;
    }
}