395 lines
12 KiB
PHP
395 lines
12 KiB
PHP
<?php
|
|
/**
|
|
* Represents the membership of a user to a user group.
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License along
|
|
* with this program; if not, write to the Free Software Foundation, Inc.,
|
|
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
* http://www.gnu.org/copyleft/gpl.html
|
|
*
|
|
* @file
|
|
*/
|
|
|
|
use MediaWiki\MediaWikiServices;
|
|
use Wikimedia\Assert\Assert;
|
|
use Wikimedia\Assert\ParameterTypeException;
|
|
use Wikimedia\Rdbms\IDatabase;
|
|
|
|
/**
|
|
* Represents a "user group membership" -- a specific instance of a user belonging
|
|
* to a group. For example, the fact that user Mary belongs to the sysop group is a
|
|
* user group membership.
|
|
*
|
|
* The class is a pure value object. Use UserGroupManager to modify user group memberships.
|
|
*
|
|
* @since 1.29
|
|
*/
|
|
class UserGroupMembership {
|
|
|
|
/** @var int The ID of the user who belongs to the group */
|
|
private $userId;
|
|
|
|
/** @var string */
|
|
private $group;
|
|
|
|
/** @var string|null Timestamp of expiry in TS_MW format, or null if no expiry */
|
|
private $expiry;
|
|
|
|
/** @var bool Expiration flag */
|
|
private $expired;
|
|
|
|
/**
|
|
* @param int $userId The ID of the user who belongs to the group
|
|
* @param string|null $group The internal group name
|
|
* @param string|null $expiry Timestamp of expiry in TS_MW format, or null if no expiry
|
|
*/
|
|
public function __construct( $userId = 0, $group = null, $expiry = null ) {
|
|
self::assertValidSpec( $userId, $group, $expiry );
|
|
$this->userId = (int)$userId;
|
|
$this->group = $group;
|
|
$this->expiry = $expiry ?: null;
|
|
$this->expired = $expiry ? wfTimestampNow() > $expiry : false;
|
|
}
|
|
|
|
/**
|
|
* Asserts that the given parameters could be used to construct a UserGroupMembership object
|
|
*
|
|
* @param int $userId
|
|
* @param string|null $group
|
|
* @param string|null $expiry
|
|
*
|
|
* @throws ParameterTypeException
|
|
*/
|
|
private static function assertValidSpec( $userId, $group, $expiry ) {
|
|
Assert::parameterType( 'integer', $userId, '$userId' );
|
|
Assert::parameterType( [ 'string', 'null' ], $group, '$group' );
|
|
Assert::parameterType( [ 'string', 'null' ], $expiry, '$expiry' );
|
|
}
|
|
|
|
/**
|
|
* @return int
|
|
*/
|
|
public function getUserId() {
|
|
return $this->userId;
|
|
}
|
|
|
|
/**
|
|
* @return string
|
|
*/
|
|
public function getGroup() {
|
|
return $this->group;
|
|
}
|
|
|
|
/**
|
|
* @return string|null Timestamp of expiry in TS_MW format, or null if no expiry
|
|
*/
|
|
public function getExpiry() {
|
|
return $this->expiry;
|
|
}
|
|
|
|
/**
|
|
* @deprecated since 1.35
|
|
* @param $row
|
|
*/
|
|
protected function initFromRow( $row ) {
|
|
wfDeprecated( __METHOD__, '1.35' );
|
|
$this->userId = (int)$row->ug_user;
|
|
$this->group = $row->ug_group;
|
|
$this->expiry = $row->ug_expiry === null ?
|
|
null :
|
|
wfTimestamp( TS_MW, $row->ug_expiry );
|
|
}
|
|
|
|
/**
|
|
* Creates a new UserGroupMembership object from a database row.
|
|
*
|
|
* @param stdClass $row The row from the user_groups table
|
|
* @return UserGroupMembership
|
|
*
|
|
* @deprecated since 1.35, use UserGroupMembership constructor instead
|
|
*/
|
|
public static function newFromRow( $row ) {
|
|
wfDeprecated( __METHOD__, '1.35' );
|
|
return new self(
|
|
(int)$row->ug_user,
|
|
$row->ug_group,
|
|
$row->ug_expiry === null ? null : wfTimestamp( TS_MW, $row->ug_expiry )
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Returns the list of user_groups fields that should be selected to create
|
|
* a new user group membership.
|
|
* @return array
|
|
*
|
|
* @deprecated since 1.35, use UserGroupManager::getQueryInfo instead
|
|
*/
|
|
public static function selectFields() {
|
|
wfDeprecated( __METHOD__, '1.35' );
|
|
return MediaWikiServices::getInstance()->getUserGroupManager()->getQueryInfo()['fields'];
|
|
}
|
|
|
|
/**
|
|
* Delete the row from the user_groups table.
|
|
*
|
|
* @throws MWException
|
|
* @param IDatabase|null $dbw Optional master database connection to use
|
|
* @return bool Whether or not anything was deleted
|
|
*
|
|
* @deprecated since 1.35, use UserGroupManager::removeUserFromGroup instead
|
|
*/
|
|
public function delete( IDatabase $dbw = null ) {
|
|
wfDeprecated( __METHOD__, '1.35' );
|
|
return MediaWikiServices::getInstance()
|
|
->getUserGroupManager()
|
|
->removeUserFromGroup(
|
|
// TODO: we're forced to forge a User instance here because we don't have
|
|
// a username around to create an artificial UserIdentityValue
|
|
// and the username is being used down the tree. This will be gone once the
|
|
// deprecated method is removed
|
|
User::newFromId( $this->getUserId() ),
|
|
$this->group
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Insert a user right membership into the database. When $allowUpdate is false,
|
|
* the function fails if there is a conflicting membership entry (same user and
|
|
* group) already in the table.
|
|
*
|
|
* @throws UnexpectedValueException
|
|
* @param bool $allowUpdate Whether to perform "upsert" instead of INSERT
|
|
* @param IDatabase|null $dbw If you have one available
|
|
* @return bool Whether or not anything was inserted
|
|
*
|
|
* @deprecated since 1.35, use UserGroupManager::addUserToGroup instead
|
|
*/
|
|
public function insert( $allowUpdate = false, IDatabase $dbw = null ) {
|
|
wfDeprecated( __METHOD__, '1.35' );
|
|
return MediaWikiServices::getInstance()
|
|
->getUserGroupManager()
|
|
->addUserToGroup(
|
|
// TODO: we're forced to forge a User instance here because we don't have
|
|
// a username around to create an artificial UserIdentityValue
|
|
// and the username is being used down the tree. This will be gone once the
|
|
// deprecated method is removed
|
|
User::newFromId( $this->getUserId() ),
|
|
$this->group,
|
|
$this->expiry,
|
|
$allowUpdate
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Has the membership expired?
|
|
*
|
|
* @return bool
|
|
*/
|
|
public function isExpired() {
|
|
return $this->expired;
|
|
}
|
|
|
|
/**
|
|
* Purge expired memberships from the user_groups table
|
|
*
|
|
* @return int|bool false if purging wasn't attempted (e.g. because of
|
|
* readonly), the number of rows purged (might be 0) otherwise
|
|
*
|
|
* @deprecated since 1.35, use UserGroupManager::purgeExpired instead
|
|
*/
|
|
public static function purgeExpired() {
|
|
wfDeprecated( __METHOD__, '1.35' );
|
|
return MediaWikiServices::getInstance()
|
|
->getUserGroupManager()
|
|
->purgeExpired();
|
|
}
|
|
|
|
/**
|
|
* Returns UserGroupMembership objects for all the groups a user currently
|
|
* belongs to.
|
|
*
|
|
* @param int $userId ID of the user to search for
|
|
* @param IDatabase|null $db unused since 1.35
|
|
* @return UserGroupMembership[] Associative array of (group name => UserGroupMembership object)
|
|
*
|
|
* @deprecated since 1.35, use UserGroupManager::getUserGroupMemberships instead
|
|
*/
|
|
public static function getMembershipsForUser( $userId, IDatabase $db = null ) {
|
|
wfDeprecated( __METHOD__, '1.35' );
|
|
return MediaWikiServices::getInstance()
|
|
->getUserGroupManager()
|
|
->getUserGroupMemberships(
|
|
// TODO: we're forced to forge a User instance here because we don't have
|
|
// a username around to create an artificial UserIdentityValue
|
|
// and the username is being used down the tree. This will be gone once the
|
|
// deprecated method is removed
|
|
User::newFromId( $userId )
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Returns a UserGroupMembership object that pertains to the given user and group,
|
|
* or false if the user does not belong to that group (or the assignment has
|
|
* expired).
|
|
*
|
|
* @param int $userId ID of the user to search for
|
|
* @param string $group User group name
|
|
* @param IDatabase|null $db unused since 1.35
|
|
* @return UserGroupMembership|false
|
|
*
|
|
* @deprecated since 1.35, use UserGroupManager::getUserGroupMemberships instead
|
|
*/
|
|
public static function getMembership( $userId, $group, IDatabase $db = null ) {
|
|
wfDeprecated( __METHOD__, '1.35' );
|
|
$ugms = MediaWikiServices::getInstance()
|
|
->getUserGroupManager()
|
|
->getUserGroupMemberships(
|
|
// TODO: we're forced to forge a User instance here because we don't have
|
|
// a username around to create an artificial UserIdentityValue
|
|
// and the username is being used down the tree. This will be gone once the
|
|
// deprecated method is removed
|
|
User::newFromId( $userId )
|
|
);
|
|
return $ugms[$group] ?? false;
|
|
}
|
|
|
|
/**
|
|
* Gets a link for a user group, possibly including the expiry date if relevant.
|
|
*
|
|
* @param string|UserGroupMembership $ugm Either a group name as a string, or
|
|
* a UserGroupMembership object
|
|
* @param IContextSource $context
|
|
* @param string $format Either 'wiki' or 'html'
|
|
* @param string|null $userName If you want to use the group member message
|
|
* ("administrator"), pass the name of the user who belongs to the group; it
|
|
* is used for GENDER of the group member message. If you instead want the
|
|
* group name message ("Administrators"), omit this parameter.
|
|
* @return string
|
|
*/
|
|
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;
|
|
}
|
|
|
|
/**
|
|
* Gets the localized friendly name for a group, if it exists. For example,
|
|
* "Administrators" or "Bureaucrats"
|
|
*
|
|
* @param string $group Internal group name
|
|
* @return string Localized friendly group name
|
|
*/
|
|
public static function getGroupName( $group ) {
|
|
$msg = wfMessage( "group-$group" );
|
|
return $msg->isBlank() ? $group : $msg->text();
|
|
}
|
|
|
|
/**
|
|
* Gets the localized name for a member of a group, if it exists. For example,
|
|
* "administrator" or "bureaucrat"
|
|
*
|
|
* @param string $group Internal group name
|
|
* @param string $username Username for gender
|
|
* @return string Localized name for group member
|
|
*/
|
|
public static function getGroupMemberName( $group, $username ) {
|
|
$msg = wfMessage( "group-$group-member", $username );
|
|
return $msg->isBlank() ? $group : $msg->text();
|
|
}
|
|
|
|
/**
|
|
* Gets the title of a page describing a particular user group. When the name
|
|
* of the group appears in the UI, it can link to this page.
|
|
*
|
|
* @param string $group Internal group name
|
|
* @return Title|bool Title of the page if it exists, false otherwise
|
|
*/
|
|
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;
|
|
}
|
|
|
|
/**
|
|
* Compares two pure value objects
|
|
*
|
|
* @param UserGroupMembership $ugm
|
|
* @return bool
|
|
*
|
|
* @since 1.35
|
|
*/
|
|
public function equals( UserGroupMembership $ugm ) {
|
|
return (
|
|
$ugm->getUserId() === $this->userId
|
|
&& $ugm->getGroup() === $this->group
|
|
);
|
|
}
|
|
|
|
}
|