Add new authentication-related hooks (and remove one) replacing some AuthPlugin methods

* LocalUserCreated: Replaces AuthPlugin::initUser()
* UserGroupsChanged: Replaces AuthPlugin::updateExternalDBGroups()
** The similar UserRights hook is deprecated, mainly to get rid of the
   passing of $user by reference.
* UserIsHidden: Replaces AuthPluginUser::isHidden()
* UserIsLocked: Replaces AuthPluginUser::isLocked()
* UserLoggedIn: Replaces AuthPlugin::updateUser()

Also, AuthPlugin::updateExternalDB() is deprecated in favor of the
existing UserSaveSettings hook.

Also, 'ResetSessionID' has been removed. Nothing uses it, I don't know
why I even added it in the first place.

Also, replacing the User object passed to AuthPlugin::initUser() and
AuthPlugin::updateUser() will now raise a warning.

Change-Id: If7474cfb26a29b11c2e78147069419ca3b1cba95

RELEASE-NOTES-1.26

@@ -30,6 +30,17 @@ production.
 * Custom LESS functions (defined via $wgResourceLoaderLESSFunctions)
   have been removed, after being deprecated in 1.24.
 * $wgAlwaysUseTidy has been removed.
+* ResetSessionID hook has been removed. Nothing seems to use it.
+* Certain AuthPlugin methods are deprecated in favor of new hooks:
+** AuthPlugin::initUser() is replaced by LocalUserCreated.
+** AuthPlugin::updateUser() is replaced by UserLoggedIn.
+** AuthPlugin::updateExternalDB() is replaced by the existing UserSaveSettings.
+** AuthPlugin::updateExternalDBGroups() is replaced by UserGroupsChanged.
+** AuthPluginUser::isHidden() is replaced by UserIsHidden.
+** AuthPluginUser::isLocked() is replaced by UserIsLocked.
+* The UserRights hook is deprecated in favor of the new UserGroupsChanged hook.
+* AuthPlugin::initUser() and AuthPlugin::updateUser() should no longer replace
+  the passed User object.
 
 === New features in 1.26 ===
 * (T51506) Now action=info gives estimates of actual watchers for a page.

docs/hooks.txt

@@ -1844,6 +1844,10 @@ optional localisation messages
 &$ignored: Array of ignored message keys
 &$optional: Array of optional message keys
 
+'LocalUserCreated': Called when a local user has been created
+$user: User object for the created user
+$autocreated: Boolean, whether this was an auto-creation
+
 'LogEventsListGetExtraInputs': When getting extra inputs to display on
 Special:Log for a specific log type
 $type: String of log type being displayed
@@ -2447,10 +2451,6 @@ $context: (IContextSource) The RequestContext the skin is being created for.
 $user: The user having their password expiration reset
 &$newExpire: The new expiration date
 
-'ResetSessionID': Called from wfResetSessionID
-$oldSessionID: old session id
-$newSessionID: new session id
-
 'ResourceLoaderForeignApiModules': Called from ResourceLoaderForeignApiModule.
 Use this to add dependencies to 'mediawiki.ForeignApi' module when you wish
 to override its behavior. See the module docs for more information.
@@ -3203,6 +3203,11 @@ $context: IContextSource object
 $user: User to get rights for
 &$rights: Current rights
 
+'UserGroupsChanged': Called after user groups are changed.
+$user: User whose groups changed
+$added: Groups added
+$removed: Groups removed
+
 'UserIsBlockedFrom': Check if a user is blocked from a specific page (for
 specific block exemptions).
 $user: User in question
@@ -3220,6 +3225,14 @@ $ip: User's IP address
 false if a UserGetRights hook might remove the named right.
 $right: The user right being checked
 
+'UserIsHidden': Check if the user's name should be hidden. See User::isHidden().
+$user: User in question.
+&$hidden: Set true if the user's name should be hidden.
+
+'UserIsLocked': Check if the user is locked. See User::isLocked().
+$user: User in question.
+&$locked: Set true if the user should be locked.
+
 'UserLoadAfterLoadFromSession': Called to authenticate users on external or
 environmental means; occurs after session is loaded.
 $user: user object being loaded
@@ -3243,6 +3256,9 @@ database.
 $user: User object
 &$options: Options, can be modified.
 
+'UserLoggedIn': Called after a user is logged in
+$user: User object for the logged-in user
+
 'UserLoginComplete': After a user has logged in.
 $user: the user object that was created on login
 $inject_html: Any HTML to inject after the "logged in" message.
@@ -3288,8 +3304,9 @@ message(s).
 $user: user retrieving new talks messages
 $talks: array of new talks page(s)
 
-'UserRights': After a user's group memberships are changed.
+'UserRights': DEPRECATED! Use UserGroupsChanged instead.
-$user: User object that was changed
+After a user's group memberships are changed.
+&$user: User object that was changed
 $add: Array of strings corresponding to groups added
 $remove: Array of strings corresponding to groups removed
 

includes/AuthPlugin.php

@@ -120,6 +120,8 @@ class AuthPlugin {
 	 * The User object is passed by reference so it can be modified; don't
 	 * forget the & on your function declaration.
 	 *
+	 * @deprecated since 1.26, use the UserLoggedIn hook instead. And assigning
+	 *  a different User object to $user is no longer supported.
 	 * @param User $user
 	 * @return bool
 	 */
@@ -204,6 +206,7 @@ class AuthPlugin {
 	 * Update user information in the external authentication database.
 	 * Return true if successful.
 	 *
+	 * @deprecated since 1.26, use the UserSaveSettings hook instead.
 	 * @param User $user
 	 * @return bool
 	 */
@@ -215,6 +218,7 @@ class AuthPlugin {
 	 * Update user groups in the external authentication database.
 	 * Return true if successful.
 	 *
+	 * @deprecated since 1.26, use the UserGroupsChanged hook instead.
 	 * @param User $user
 	 * @param array $addgroups Groups to add.
 	 * @param array $delgroups Groups to remove.
@@ -278,6 +282,8 @@ class AuthPlugin {
 	 * The User object is passed by reference so it can be modified; don't
 	 * forget the & on your function declaration.
 	 *
+	 * @deprecated since 1.26, use the UserLoggedIn hook instead. And assigning
+	 *  a different User object to $user is no longer supported.
 	 * @param User $user
 	 * @param bool $autocreate True if user is being autocreated on login
 	 */
@@ -326,11 +332,21 @@ class AuthPluginUser {
 		return -1;
 	}
 
+	/**
+	 * Indicate whether the user is locked
+	 * @deprecated since 1.26, use the UserIsLocked hook instead.
+	 * @return bool
+	 */
 	public function isLocked() {
 		# Override this!
 		return false;
 	}
 
+	/**
+	 * Indicate whether the user is hidden
+	 * @deprecated since 1.26, use the UserIsHidden hook instead.
+	 * @return bool
+	 */
 	public function isHidden() {
 		# Override this!
 		return false;

includes/GlobalFunctions.php

@@ -3466,7 +3466,6 @@ function wfResetSessionID() {
 		$_SESSION = $tmp;
 	}
 	$newSessionId = session_id();
-	Hooks::run( 'ResetSessionID', array( $oldSessionId, $newSessionId ) );
 }
 
 /**

includes/Preferences.php

@@ -1433,10 +1433,10 @@ class Preferences {
 			}
 
 			Hooks::run( 'PreferencesFormPreSave', array( $formData, $form, $user, &$result ) );
-			$user->saveSettings();
 		}
 
 		$wgAuth->updateExternalDB( $user );
+		$user->saveSettings();
 
 		return $result;
 	}

includes/User.php

@@ -1430,8 +1430,8 @@ class User implements IDBAccessObject {
 		foreach ( $toPromote as $group ) {
 			$this->addGroup( $group );
 		}
-
 		// update groups in external authentication database
+		Hooks::run( 'UserGroupsChanged', array( $this, $toPromote, array() ) );
 		$wgAuth->updateExternalDBGroups( $this, $toPromote );
 
 		$newGroups = array_merge( $oldGroups, $toPromote ); // all groups
@@ -1993,6 +1993,7 @@ class User implements IDBAccessObject {
 		global $wgAuth;
 		$authUser = $wgAuth->getUserInstance( $this );
 		$this->mLocked = (bool)$authUser->isLocked();
+		Hooks::run( 'UserIsLocked', array( $this, &$this->mLocked ) );
 		return $this->mLocked;
 	}
 
@@ -2010,6 +2011,7 @@ class User implements IDBAccessObject {
 			global $wgAuth;
 			$authUser = $wgAuth->getUserInstance( $this );
 			$this->mHideName = (bool)$authUser->isHidden();
+			Hooks::run( 'UserIsHidden', array( $this, &$this->mHideName ) );
 		}
 		return $this->mHideName;
 	}

includes/specials/SpecialUserlogin.php

@@ -674,7 +674,12 @@ class LoginForm extends SpecialPage {
 		$u->setRealName( $this->mRealName );
 		$u->setToken();
 
+		Hooks::run( 'LocalUserCreated', array( $u, $autocreate ) );
+		$oldUser = $u;
 		$wgAuth->initUser( $u, $autocreate );
+		if ( $oldUser !== $u ) {
+			wfWarn( get_class( $wgAuth ) . '::initUser() replaced the user object' );
+		}
 
 		$u->saveSettings();
 
@@ -820,7 +825,12 @@ class LoginForm extends SpecialPage {
 			$retval = self::RESET_PASS;
 			$this->mAbortLoginErrorMsg = 'resetpass-expired';
 		} else {
+			Hooks::run( 'UserLoggedIn', array( $u ) );
+			$oldUser = $u;
 			$wgAuth->updateUser( $u );
+			if ( $oldUser !== $u ) {
+				wfWarn( get_class( $wgAuth ) . '::updateUser() replaced the user object' );
+			}
 			$wgUser = $u;
 			// This should set it for OutputPage and the Skin
 			// which is needed or the personal links will be

includes/specials/SpecialUserrights.php

@@ -269,6 +269,7 @@ class UserrightsPage extends SpecialPage {
 		$user->invalidateCache();
 
 		// update groups in external authentication database
+		Hooks::run( 'UserGroupsChanged', array( $user, $add, $remove ) );
 		$wgAuth->updateExternalDBGroups( $user, $add, $remove );
 
 		wfDebug( 'oldGroups: ' . print_r( $oldGroups, true ) . "\n" );