3 * Represents the membership of a user to a user group.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
23 use Wikimedia\Rdbms\IDatabase
;
26 * Represents a "user group membership" -- a specific instance of a user belonging
27 * to a group. For example, the fact that user Mary belongs to the sysop group is a
28 * user group membership.
30 * The class encapsulates rows in the user_groups table. The logic is low-level and
31 * doesn't run any hooks. Often, you will want to call User::addGroup() or
32 * User::removeGroup() instead.
36 class UserGroupMembership
{
37 /** @var int The ID of the user who belongs to the group */
43 /** @var string|null Timestamp of expiry in TS_MW format, or null if no expiry */
47 * @param int $userId The ID of the user who belongs to the group
48 * @param string $group The internal group name
49 * @param string|null $expiry Timestamp of expiry in TS_MW format, or null if no expiry
51 public function __construct( $userId = 0, $group = null, $expiry = null ) {
52 global $wgDisableUserGroupExpiry;
53 if ( $wgDisableUserGroupExpiry ) {
57 $this->userId
= (int)$userId;
58 $this->group
= $group; // TODO throw on invalid group?
59 $this->expiry
= $expiry ?
: null;
65 public function getUserId() {
72 public function getGroup() {
77 * @return string|null Timestamp of expiry in TS_MW format, or null if no expiry
79 public function getExpiry() {
80 global $wgDisableUserGroupExpiry;
81 if ( $wgDisableUserGroupExpiry ) {
88 protected function initFromRow( $row ) {
89 global $wgDisableUserGroupExpiry;
91 $this->userId
= (int)$row->ug_user
;
92 $this->group
= $row->ug_group
;
93 if ( $wgDisableUserGroupExpiry ) {
96 $this->expiry
= $row->ug_expiry
=== null ?
98 wfTimestamp( TS_MW
, $row->ug_expiry
);
103 * Creates a new UserGroupMembership object from a database row.
105 * @param stdClass $row The row from the user_groups table
106 * @return UserGroupMembership
108 public static function newFromRow( $row ) {
110 $ugm->initFromRow( $row );
115 * Returns the list of user_groups fields that should be selected to create
116 * a new user group membership.
119 public static function selectFields() {
120 global $wgDisableUserGroupExpiry;
121 if ( $wgDisableUserGroupExpiry ) {
136 * Delete the row from the user_groups table.
138 * @throws MWException
139 * @param IDatabase|null $dbw Optional master database connection to use
140 * @return bool Whether or not anything was deleted
142 public function delete( IDatabase
$dbw = null ) {
143 global $wgDisableUserGroupExpiry;
144 if ( wfReadOnly() ) {
148 if ( $dbw === null ) {
149 $dbw = wfGetDB( DB_MASTER
);
152 if ( $wgDisableUserGroupExpiry ) {
153 $dbw->delete( 'user_groups', $this->getDatabaseArray( $dbw ), __METHOD__
);
157 [ 'ug_user' => $this->userId
, 'ug_group' => $this->group
],
160 if ( !$dbw->affectedRows() ) {
164 // Remember that the user was in this group
166 'user_former_groups',
167 [ 'ufg_user' => $this->userId
, 'ufg_group' => $this->group
],
175 * Insert a user right membership into the database. When $allowUpdate is false,
176 * the function fails if there is a conflicting membership entry (same user and
177 * group) already in the table.
179 * @throws MWException
180 * @param bool $allowUpdate Whether to perform "upsert" instead of INSERT
181 * @param IDatabase|null $dbw If you have one available
182 * @return bool Whether or not anything was inserted
184 public function insert( $allowUpdate = false, IDatabase
$dbw = null ) {
185 global $wgDisableUserGroupExpiry;
186 if ( $dbw === null ) {
187 $dbw = wfGetDB( DB_MASTER
);
190 // Purge old, expired memberships from the DB
191 self
::purgeExpired( $dbw );
193 // Check that the values make sense
194 if ( $this->group
=== null ) {
195 throw new UnexpectedValueException(
196 'Don\'t try inserting an uninitialized UserGroupMembership object' );
197 } elseif ( $this->userId
<= 0 ) {
198 throw new UnexpectedValueException(
199 'UserGroupMembership::insert() needs a positive user ID. ' .
200 'Did you forget to add your User object to the database before calling addGroup()?' );
203 $row = $this->getDatabaseArray( $dbw );
204 $dbw->insert( 'user_groups', $row, __METHOD__
, [ 'IGNORE' ] );
205 $affected = $dbw->affectedRows();
207 // Don't collide with expired user group memberships
208 // Do this after trying to insert, in order to avoid locking
209 if ( !$wgDisableUserGroupExpiry && !$affected ) {
211 'ug_user' => $row['ug_user'],
212 'ug_group' => $row['ug_group'],
214 // if we're unconditionally updating, check that the expiry is not already the
215 // same as what we are trying to update it to; otherwise, only update if
216 // the expiry date is in the past
217 if ( $allowUpdate ) {
218 if ( $this->expiry
) {
219 $conds[] = 'ug_expiry IS NULL OR ug_expiry != ' .
220 $dbw->addQuotes( $dbw->timestamp( $this->expiry
) );
222 $conds[] = 'ug_expiry IS NOT NULL';
225 $conds[] = 'ug_expiry < ' . $dbw->addQuotes( $dbw->timestamp() );
228 $row = $dbw->selectRow( 'user_groups', $this::selectFields(), $conds, __METHOD__
);
232 [ 'ug_expiry' => $this->expiry ?
$dbw->timestamp( $this->expiry
) : null ],
233 [ 'ug_user' => $row->ug_user
, 'ug_group' => $row->ug_group
],
235 $affected = $dbw->affectedRows();
239 return $affected > 0;
243 * Get an array suitable for passing to $dbw->insert() or $dbw->update()
244 * @param IDatabase $db
247 protected function getDatabaseArray( IDatabase
$db ) {
248 global $wgDisableUserGroupExpiry;
251 'ug_user' => $this->userId
,
252 'ug_group' => $this->group
,
254 if ( !$wgDisableUserGroupExpiry ) {
255 $a['ug_expiry'] = $this->expiry ?
$db->timestamp( $this->expiry
) : null;
261 * Has the membership expired?
264 public function isExpired() {
265 global $wgDisableUserGroupExpiry;
266 if ( $wgDisableUserGroupExpiry ||
!$this->expiry
) {
269 return wfTimestampNow() > $this->expiry
;
274 * Purge expired memberships from the user_groups table
276 * @param IDatabase|null $dbw
278 public static function purgeExpired( IDatabase
$dbw = null ) {
279 global $wgDisableUserGroupExpiry;
280 if ( $wgDisableUserGroupExpiry ||
wfReadOnly() ) {
284 if ( $dbw === null ) {
285 $dbw = wfGetDB( DB_MASTER
);
288 DeferredUpdates
::addUpdate( new AtomicSectionUpdate(
291 function ( IDatabase
$dbw, $fname ) {
292 $expiryCond = [ 'ug_expiry < ' . $dbw->addQuotes( $dbw->timestamp() ) ];
293 $res = $dbw->select( 'user_groups', self
::selectFields(), $expiryCond, $fname );
295 // save an array of users/groups to insert to user_former_groups
296 $usersAndGroups = [];
297 foreach ( $res as $row ) {
298 $usersAndGroups[] = [ 'ufg_user' => $row->ug_user
, 'ufg_group' => $row->ug_group
];
302 $dbw->delete( 'user_groups', $expiryCond, $fname );
304 // and push the groups to user_former_groups
305 $dbw->insert( 'user_former_groups', $usersAndGroups, __METHOD__
, [ 'IGNORE' ] );
311 * Returns UserGroupMembership objects for all the groups a user currently
314 * @param int $userId ID of the user to search for
315 * @param IDatabase|null $db Optional database connection
316 * @return array Associative array of (group name => UserGroupMembership object)
318 public static function getMembershipsForUser( $userId, IDatabase
$db = null ) {
320 $db = wfGetDB( DB_REPLICA
);
323 $res = $db->select( 'user_groups',
324 self
::selectFields(),
325 [ 'ug_user' => $userId ],
329 foreach ( $res as $row ) {
330 $ugm = self
::newFromRow( $row );
331 if ( !$ugm->isExpired() ) {
332 $ugms[$ugm->group
] = $ugm;
340 * Returns a UserGroupMembership object that pertains to the given user and group,
341 * or false if the user does not belong to that group (or the assignment has
344 * @param int $userId ID of the user to search for
345 * @param string $group User group name
346 * @param IDatabase|null $db Optional database connection
347 * @return UserGroupMembership|false
349 public static function getMembership( $userId, $group, IDatabase
$db = null ) {
351 $db = wfGetDB( DB_REPLICA
);
354 $row = $db->selectRow( 'user_groups',
355 self
::selectFields(),
356 [ 'ug_user' => $userId, 'ug_group' => $group ],
362 $ugm = self
::newFromRow( $row );
363 if ( !$ugm->isExpired() ) {
371 * Gets a link for a user group, possibly including the expiry date if relevant.
373 * @param string|UserGroupMembership $ugm Either a group name as a string, or
374 * a UserGroupMembership object
375 * @param IContextSource $context
376 * @param string $format Either 'wiki' or 'html'
377 * @param string|null $userName If you want to use the group member message
378 * ("administrator"), pass the name of the user who belongs to the group; it
379 * is used for GENDER of the group member message. If you instead want the
380 * group name message ("Administrators"), omit this parameter.
383 public static function getLink( $ugm, IContextSource
$context, $format,
386 if ( $format !== 'wiki' && $format !== 'html' ) {
387 throw new MWException( 'UserGroupMembership::getLink() $format parameter should be ' .
388 "'wiki' or 'html'" );
391 if ( $ugm instanceof UserGroupMembership
) {
392 $expiry = $ugm->getExpiry();
393 $group = $ugm->getGroup();
399 if ( $userName !== null ) {
400 $groupName = self
::getGroupMemberName( $group, $userName );
402 $groupName = self
::getGroupName( $group );
405 // link to the group description page, if it exists
406 $linkTitle = self
::getGroupPage( $group );
408 if ( $format === 'wiki' ) {
409 $linkPage = $linkTitle->getFullText();
410 $groupLink = "[[$linkPage|$groupName]]";
412 $groupLink = Linker
::link( $linkTitle, htmlspecialchars( $groupName ) );
415 $groupLink = htmlspecialchars( $groupName );
419 // format the expiry to a nice string
420 $uiLanguage = $context->getLanguage();
421 $uiUser = $context->getUser();
422 $expiryDT = $uiLanguage->userTimeAndDate( $expiry, $uiUser );
423 $expiryD = $uiLanguage->userDate( $expiry, $uiUser );
424 $expiryT = $uiLanguage->userTime( $expiry, $uiUser );
425 if ( $format === 'html' ) {
426 $groupLink = Message
::rawParam( $groupLink );
428 return $context->msg( 'group-membership-link-with-expiry' )
429 ->params( $groupLink, $expiryDT, $expiryD, $expiryT )->text();
436 * Gets the localized friendly name for a group, if it exists. For example,
437 * "Administrators" or "Bureaucrats"
439 * @param string $group Internal group name
440 * @return string Localized friendly group name
442 public static function getGroupName( $group ) {
443 $msg = wfMessage( "group-$group" );
444 return $msg->isBlank() ?
$group : $msg->text();
448 * Gets the localized name for a member of a group, if it exists. For example,
449 * "administrator" or "bureaucrat"
451 * @param string $group Internal group name
452 * @param string $username Username for gender
453 * @return string Localized name for group member
455 public static function getGroupMemberName( $group, $username ) {
456 $msg = wfMessage( "group-$group-member", $username );
457 return $msg->isBlank() ?
$group : $msg->text();
461 * Gets the title of a page describing a particular user group. When the name
462 * of the group appears in the UI, it can link to this page.
464 * @param string $group Internal group name
465 * @return Title|bool Title of the page if it exists, false otherwise
467 public static function getGroupPage( $group ) {
468 $msg = wfMessage( "grouppage-$group" )->inContentLanguage();
469 if ( $msg->exists() ) {
470 $title = Title
::newFromText( $msg->text() );
471 if ( is_object( $title ) ) {