updated to MediaWiki 1.14.0

1 files changed, 700 insertions, 359 deletions

diff --git a/includes/User.php b/includes/User.php
index 4e39d678..9fee089c 100644
--- a/includes/User.php
+++ b/includes/User.php
@@ -1,20 +1,29 @@
 <?php
 /**
- * See user.txt
+ * Implements the User class for the %MediaWiki software.
  * @file
  */
 
-# Number of characters in user_token field
+/**
+ * \int Number of characters in user_token field.
+ * @ingroup Constants
+ */
 define( 'USER_TOKEN_LENGTH', 32 );
 
-# Serialized record version
+/**
+ * \int Serialized record version.
+ * @ingroup Constants
+ */
 define( 'MW_USER_VERSION', 6 );
 
-# Some punctuation to prevent editing from broken text-mangling proxies.
+/**
+ * \string Some punctuation to prevent editing from broken text-mangling proxies.
+ * @ingroup Constants
+ */
 define( 'EDIT_TOKEN_SUFFIX', '+\\' );
 
 /**
- * Thrown by User::setPassword() on error
+ * Thrown by User::setPassword() on error.
  * @ingroup Exception
  */
 class PasswordError extends MWException {
@@ -34,11 +43,13 @@ class PasswordError extends MWException {
 class User {
 
 	/**
-	 * A list of default user toggles, i.e. boolean user preferences that are
-	 * displayed by Special:Preferences as checkboxes. This list can be
-	 * extended via the UserToggles hook or $wgContLang->getExtraUserToggles().
+	 * \type{\arrayof{\string}} A list of default user toggles, i.e., boolean user 
+         * preferences that are displayed by Special:Preferences as checkboxes.
+	 * This list can be extended via the UserToggles hook or by
+	 * $wgContLang::getExtraUserToggles().
+	 * @showinitializer
 	 */
-	static public $mToggles = array(
+	public static $mToggles = array(
 		'highlightbroken',
 		'justify',
 		'hideminor',
@@ -71,21 +82,26 @@ class User {
 		'showjumplinks',
 		'uselivepreview',
 		'forceeditsummary',
-		'watchlisthideown',
-		'watchlisthidebots',
 		'watchlisthideminor',
+		'watchlisthidebots',
+		'watchlisthideown',
+		'watchlisthideanons',
+		'watchlisthideliu',
 		'ccmeonemails',
 		'diffonly',
 		'showhiddencats',
+		'noconvertlink',
+		'norollbackdiff',
 	);
 
 	/**
-	 * List of member variables which are saved to the shared cache (memcached).
-	 * Any operation which changes the corresponding database fields must
-	 * call a cache-clearing function.
+	 * \type{\arrayof{\string}} List of member variables which are saved to the 
+	 * shared cache (memcached). Any operation which changes the 
+	 * corresponding database fields must call a cache-clearing function.
+	 * @showinitializer
 	 */
 	static $mCacheVars = array(
-		# user table
+		// user table
 		'mId',
 		'mName',
 		'mRealName',
@@ -101,13 +117,15 @@ class User {
 		'mEmailTokenExpires',
 		'mRegistration',
 		'mEditCount',
-		# user_group table
+		// user_group table
 		'mGroups',
 	);
 
 	/**
-	 * Core rights
-	 * Each of these should have a corresponding message of the form "right-$right"
+	 * \type{\arrayof{\string}} Core rights.
+	 * Each of these should have a corresponding message of the form 
+	 * "right-$right".
+	 * @showinitializer
 	 */
 	static $mCoreRights = array(
 		'apihighlimits',
@@ -132,6 +150,9 @@ class User {
 		'markbotedits',
 		'minoredit',
 		'move',
+		'movefile',
+		'move-rootuserpages',
+		'move-subpages',
 		'nominornewtalk',
 		'noratelimit',
 		'patrol',
@@ -142,6 +163,7 @@ class User {
 		'reupload',
 		'reupload-shared',
 		'rollback',
+		'siteadmin',
 		'suppressredirect',
 		'trackback',
 		'undelete',
@@ -150,47 +172,57 @@ class User {
 		'upload_by_url',
 		'userrights',
 	);
-	static $mAllRights = false;
-
 	/**
-	 * The cache variable declarations
+	 * \string Cached results of getAllRights()
 	 */
+	static $mAllRights = false;
+
+	/** @name Cache variables */
+	//@{
 	var $mId, $mName, $mRealName, $mPassword, $mNewpassword, $mNewpassTime,
 		$mEmail, $mOptions, $mTouched, $mToken, $mEmailAuthenticated,
 		$mEmailToken, $mEmailTokenExpires, $mRegistration, $mGroups;
+	//@}
 
 	/**
-	 * Whether the cache variables have been loaded
+	 * \bool Whether the cache variables have been loaded.
 	 */
-	var $mDataLoaded;
+	var $mDataLoaded, $mAuthLoaded;
 
 	/**
-	 * Initialisation data source if mDataLoaded==false. May be one of:
-	 *    defaults      anonymous user initialised from class defaults
-	 *    name          initialise from mName
-	 *    id            initialise from mId
-	 *    session       log in from cookies or session if possible
+	 * \string Initialization data source if mDataLoaded==false. May be one of:
+	 *  - 'defaults'   anonymous user initialised from class defaults
+	 *  - 'name'       initialise from mName
+	 *  - 'id'         initialise from mId
+	 *  - 'session'    log in from cookies or session if possible
 	 *
 	 * Use the User::newFrom*() family of functions to set this.
 	 */
 	var $mFrom;
 
-	/**
-	 * Lazy-initialised variables, invalidated with clearInstanceCache
-	 */
+	/** @name Lazy-initialized variables, invalidated with clearInstanceCache */
+	//@{
 	var $mNewtalk, $mDatePreference, $mBlockedby, $mHash, $mSkin, $mRights,
-		$mBlockreason, $mBlock, $mEffectiveGroups;
+		$mBlockreason, $mBlock, $mEffectiveGroups, $mBlockedGlobally, 
+		$mLocked, $mHideName;
+	//@}
 
 	/**
-	 * Lightweight constructor for anonymous user
-	 * Use the User::newFrom* factory functions for other kinds of users
+	 * Lightweight constructor for an anonymous user.
+	 * Use the User::newFrom* factory functions for other kinds of users.
+	 * 
+	 * @see newFromName()
+	 * @see newFromId()
+	 * @see newFromConfirmationCode()
+	 * @see newFromSession()
+	 * @see newFromRow()
 	 */
 	function User() {
 		$this->clearInstanceCache( 'defaults' );
 	}
 
 	/**
-	 * Load the user table data for this object from the source given by mFrom
+	 * Load the user table data for this object from the source given by mFrom.
 	 */
 	function load() {
 		if ( $this->mDataLoaded ) {
@@ -219,6 +251,7 @@ class User {
 				break;
 			case 'session':
 				$this->loadFromSession();
+				wfRunHooks( 'UserLoadAfterLoadFromSession', array( $this ) );
 				break;
 			default:
 				throw new MWException( "Unrecognised value for User->mFrom: \"{$this->mFrom}\"" );
@@ -227,8 +260,8 @@ class User {
 	}
 
 	/**
-	 * Load user table data given mId
-	 * @return false if the ID does not exist, true otherwise
+	 * Load user table data, given mId has already been set.
+	 * @return \bool false if the ID does not exist, true otherwise
 	 * @private
 	 */
 	function loadFromId() {
@@ -283,6 +316,10 @@ class User {
 		global $wgMemc;
 		$wgMemc->set( $key, $data );
 	}
+	
+	
+	/** @name newFrom*() static factory methods */
+	//@{
 
 	/**
 	 * Static factory method for creation from username.
@@ -290,14 +327,14 @@ class User {
 	 * This is slightly less efficient than newFromId(), so use newFromId() if
 	 * you have both an ID and a name handy.
 	 *
-	 * @param $name String: username, validated by Title:newFromText()
-	 * @param $validate Mixed: validate username. Takes the same parameters as
+	 * @param $name \string Username, validated by Title::newFromText()
+	 * @param $validate \mixed Validate username. Takes the same parameters as
 	 *    User::getCanonicalName(), except that true is accepted as an alias
 	 *    for 'valid', for BC.
 	 *
-	 * @return User object, or null if the username is invalid. If the username
-	 *    is not present in the database, the result will be a user object with
-	 *    a name, zero user ID and default settings.
+	 * @return \type{User} The User object, or null if the username is invalid. If the 
+	 *    username is not present in the database, the result will be a user object 
+	 *    with a name, zero user ID and default settings.
 	 */
 	static function newFromName( $name, $validate = 'valid' ) {
 		if ( $validate === true ) {
@@ -315,6 +352,12 @@ class User {
 		}
 	}
 
+	/**
+	 * Static factory method for creation from a given user ID.
+	 *
+	 * @param $id \int Valid user ID
+	 * @return \type{User} The corresponding User object
+	 */
 	static function newFromId( $id ) {
 		$u = new User;
 		$u->mId = $id;
@@ -329,8 +372,8 @@ class User {
 	 *
 	 * If the code is invalid or has expired, returns NULL.
 	 *
-	 * @param $code string
-	 * @return User
+	 * @param $code \string Confirmation code
+	 * @return \type{User}
 	 */
 	static function newFromConfirmationCode( $code ) {
 		$dbr = wfGetDB( DB_SLAVE );
@@ -349,7 +392,7 @@ class User {
 	 * Create a new user object using data from session or cookies. If the
 	 * login credentials are invalid, the result is an anonymous user.
 	 *
-	 * @return User
+	 * @return \type{User}
 	 */
 	static function newFromSession() {
 		$user = new User;
@@ -360,17 +403,22 @@ class User {
 	/**
 	 * Create a new user object from a user row.
 	 * The row should have all fields from the user table in it.
+	 * @param $row array A row from the user table
+	 * @return \type{User}
 	 */
 	static function newFromRow( $row ) {
 		$user = new User;
 		$user->loadFromRow( $row );
 		return $user;
 	}
+	
+	//@}
+	
 
 	/**
-	 * Get username given an id.
-	 * @param $id Integer: database user id
-	 * @return string Nickname of a user
+	 * Get the username corresponding to a given user ID
+	 * @param $id \int User ID
+	 * @return \string The corresponding username
 	 */
 	static function whoIs( $id ) {
 		$dbr = wfGetDB( DB_SLAVE );
@@ -378,10 +426,10 @@ class User {
 	}
 
 	/**
-	 * Get the real name of a user given their identifier
+	 * Get the real name of a user given their user ID
 	 *
-	 * @param $id Int: database user id
-	 * @return string Real name of a user
+	 * @param $id \int User ID
+	 * @return \string The corresponding user's real name
 	 */
 	static function whoIsReal( $id ) {
 		$dbr = wfGetDB( DB_SLAVE );
@@ -390,12 +438,11 @@ class User {
 
 	/**
 	 * Get database id given a user name
-	 * @param $name String: nickname of a user
-	 * @return integer|null Database user id (null: if non existent
-	 * @static
+	 * @param $name \string Username
+	 * @return \types{\int,\null} The corresponding user's ID, or null if user is nonexistent
 	 */
 	static function idFromName( $name ) {
-		$nt = Title::newFromText( $name );
+		$nt = Title::makeTitleSafe( NS_USER, $name );
 		if( is_null( $nt ) ) {
 			# Illegal name
 			return null;
@@ -423,8 +470,8 @@ class User {
 	 * addresses like this, if we allowed accounts like this to be created
 	 * new users could get the old edits of these anonymous users.
 	 *
-	 * @param $name String: nickname of a user
-	 * @return bool
+	 * @param $name \string String to match
+	 * @return \bool True or false
 	 */
 	static function isIP( $name ) {
 		return preg_match('/^\d{1,3}\.\d{1,3}\.\d{1,3}\.(?:xxx|\d{1,3})$/',$name) || IP::isIPv6($name);
@@ -438,8 +485,8 @@ class User {
 	 * is longer than the maximum allowed username size or doesn't begin with
 	 * a capital letter.
 	 *
-	 * @param $name string
-	 * @return bool
+	 * @param $name \string String to match
+	 * @return \bool True or false
 	 */
 	static function isValidUserName( $name ) {
 		global $wgContLang, $wgMaxNameChars;
@@ -492,8 +539,8 @@ class User {
 	 * If an account already exists in this form, login will be blocked
 	 * by a failure to pass this function.
 	 *
-	 * @param $name string
-	 * @return bool
+	 * @param $name \string String to match
+	 * @return \bool True or false
 	 */
 	static function isUsableName( $name ) {
 		global $wgReservedUsernames;
@@ -502,8 +549,14 @@ class User {
 			return false;
 		}
 
+		static $reservedUsernames = false;
+		if ( !$reservedUsernames ) {
+			$reservedUsernames = $wgReservedUsernames;
+			wfRunHooks( 'UserGetReservedNames', array( &$reservedUsernames ) );
+		}
+
 		// Certain names may be reserved for batch processes.
-		foreach ( $wgReservedUsernames as $reserved ) {
+		foreach ( $reservedUsernames as $reserved ) {
 			if ( substr( $reserved, 0, 4 ) == 'msg:' ) {
 				$reserved = wfMsgForContent( substr( $reserved, 4 ) );
 			}
@@ -524,8 +577,8 @@ class User {
 	 * rather than in isValidUserName() to avoid disrupting
 	 * existing accounts.
 	 *
-	 * @param $name string
-	 * @return bool
+	 * @param $name \string String to match
+	 * @return \bool True or false
 	 */
 	static function isCreatableName( $name ) {
 		return
@@ -538,8 +591,8 @@ class User {
 	/**
 	 * Is the input a valid password for this user?
 	 *
-	 * @param $password String: desired password
-	 * @return bool
+	 * @param $password \string Desired password
+	 * @return \bool True or false
 	 */
 	function isValidPassword( $password ) {
 		global $wgMinimalPasswordLength, $wgContLang;
@@ -556,7 +609,7 @@ class User {
 	}
 
 	/**
-	 * Does a string look like an email address?
+	 * Does a string look like an e-mail address?
 	 *
 	 * There used to be a regular expression here, it got removed because it
 	 * rejected valid addresses. Actually just check if there is '@' somewhere
@@ -564,8 +617,8 @@ class User {
 	 *
 	 * @todo Check for RFC 2822 compilance (bug 959)
 	 *
-	 * @param $addr String: email address
-	 * @return bool
+	 * @param $addr \string E-mail address
+	 * @return \bool True or false
 	 */
 	public static function isValidEmailAddr( $addr ) {
 		$result = null;
@@ -579,12 +632,12 @@ class User {
 	/**
 	 * Given unvalidated user input, return a canonical username, or false if
 	 * the username is invalid.
-	 * @param $name string
-	 * @param $validate Mixed: type of validation to use:
-	 *                  false        No validation
-	 *                  'valid'      Valid for batch processes
-	 *                  'usable'     Valid for batch processes and login
-	 *                  'creatable'  Valid for batch processes, login and account creation
+	 * @param $name \string User input
+	 * @param $validate \types{\string,\bool} Type of validation to use:
+	 *                - false        No validation
+	 *                - 'valid'      Valid for batch processes
+	 *                - 'usable'     Valid for batch processes and login
+	 *                - 'creatable'  Valid for batch processes, login and account creation
 	 */
 	static function getCanonicalName( $name, $validate = 'valid' ) {
 		# Force usernames to capital
@@ -598,7 +651,9 @@ class User {
 			return false;
 
 		# Clean up name according to title rules
-		$t = Title::newFromText( $name );
+		$t = ($validate === 'valid') ? 
+			Title::newFromText( $name ) : Title::makeTitle( NS_USER, $name );
+		# Check for invalid titles
 		if( is_null( $t ) ) {
 			return false;
 		}
@@ -634,11 +689,10 @@ class User {
 
 	/**
 	 * Count the number of edits of a user
+	 * @todo It should not be static and some day should be merged as proper member function / deprecated -- domas
 	 *
-	 * It should not be static and some day should be merged as proper member function / deprecated -- domas
-	 *
-	 * @param $uid Int: the user ID to check
-	 * @return int
+	 * @param $uid \int User ID to check
+	 * @return \int The user's edit count
 	 */
 	static function edits( $uid ) {
 		wfProfileIn( __METHOD__ );
@@ -674,7 +728,7 @@ class User {
 	 * Return a random password. Sourced from mt_rand, so it's not particularly secure.
 	 * @todo hash random numbers to improve security, like generateToken()
 	 *
-	 * @return string
+	 * @return \string New random password
 	 */
 	static function randomPassword() {
 		global $wgMinimalPasswordLength;
@@ -691,9 +745,10 @@ class User {
 	}
 
 	/**
-	 * Set cached properties to default. Note: this no longer clears
-	 * uncached lazy-initialised properties. The constructor does that instead.
+	 * Set cached properties to default. 
 	 *
+	 * @note This no longer clears uncached lazy-initialised properties; 
+	 *       the constructor does that instead.
 	 * @private
 	 */
 	function loadDefaults( $name = false ) {
@@ -728,8 +783,7 @@ class User {
 	}
 
 	/**
-	 * Initialise php session
-	 * @deprecated use wfSetupSession()
+	 * @deprecated Use wfSetupSession().
 	 */
 	function SetupSession() {
 		wfDeprecated( __METHOD__ );
@@ -738,8 +792,8 @@ class User {
 
 	/**
 	 * Load user data from the session or login cookie. If there are no valid
-	 * credentials, initialises the user as an anon.
-	 * @return true if the user is logged in, false otherwise
+	 * credentials, initialises the user as an anonymous user.
+	 * @return \bool True if the user is logged in, false otherwise.
 	 */
 	private function loadFromSession() {
 		global $wgMemc, $wgCookiePrefix;
@@ -750,20 +804,27 @@ class User {
 			return $result;
 		}
 
-		if ( isset( $_SESSION['wsUserID'] ) ) {
-			if ( 0 != $_SESSION['wsUserID'] ) {
+		if ( isset( $_COOKIE["{$wgCookiePrefix}UserID"] ) ) {
+			$sId = intval( $_COOKIE["{$wgCookiePrefix}UserID"] );
+			if( isset( $_SESSION['wsUserID'] ) && $sId != $_SESSION['wsUserID'] ) {
+				$this->loadDefaults(); // Possible collision!
+				wfDebugLog( 'loginSessions', "Session user ID ({$_SESSION['wsUserID']}) and 
+					cookie user ID ($sId) don't match!" );
+				return false;
+			}
+			$_SESSION['wsUserID'] = $sId;
+		} else if ( isset( $_SESSION['wsUserID'] ) ) {
+			if ( $_SESSION['wsUserID'] != 0 ) {
 				$sId = $_SESSION['wsUserID'];
 			} else {
 				$this->loadDefaults();
 				return false;
 			}
-		} else if ( isset( $_COOKIE["{$wgCookiePrefix}UserID"] ) ) {
-			$sId = intval( $_COOKIE["{$wgCookiePrefix}UserID"] );
-			$_SESSION['wsUserID'] = $sId;
 		} else {
 			$this->loadDefaults();
 			return false;
 		}
+
 		if ( isset( $_SESSION['wsUserName'] ) ) {
 			$sName = $_SESSION['wsUserName'];
 		} else if ( isset( $_COOKIE["{$wgCookiePrefix}UserName"] ) ) {
@@ -806,10 +867,10 @@ class User {
 	}
 
 	/**
-	 * Load user and user_group data from the database
-	 * $this->mId must be set, this is how the user is identified.
+	 * Load user and user_group data from the database.
+	 * $this::mId must be set, this is how the user is identified.
 	 *
-	 * @return true if the user exists, false if the user is anonymous
+	 * @return \bool True if the user exists, false if the user is anonymous
 	 * @private
 	 */
 	function loadFromDatabase() {
@@ -840,7 +901,9 @@ class User {
 	}
 
 	/**
-	 * Initialise the user object from a row from the user table
+	 * Initialize this object from a row from the user table.
+	 *
+	 * @param $row \type{\arrayof{\mixed}} Row from the user table to load.
 	 */
 	function loadFromRow( $row ) {
 		$this->mDataLoaded = true;
@@ -865,7 +928,7 @@ class User {
 	}
 
 	/**
-	 * Load the groups from the database if they aren't already loaded
+	 * Load the groups from the database if they aren't already loaded.
 	 * @private
 	 */
 	function loadGroups() {
@@ -884,8 +947,8 @@ class User {
 
 	/**
 	 * Clear various cached data stored in this object.
-	 * @param $reloadFrom String: reload user and user_groups table data from a
-	 *   given source. May be "name", "id", "defaults", "session" or false for
+	 * @param $reloadFrom \string Reload user and user_groups table data from a
+	 *   given source. May be "name", "id", "defaults", "session", or false for
 	 *   no reload.
 	 */
 	function clearInstanceCache( $reloadFrom = false ) {
@@ -906,9 +969,8 @@ class User {
 	/**
 	 * Combine the language default options with any site-specific options
 	 * and add the default language variants.
-	 * Not really private cause it's called by Language class
-	 * @return array
-	 * @private
+	 *
+	 * @return \type{\arrayof{\string}} Array of options
 	 */
 	static function getDefaultOptions() {
 		global $wgNamespacesToBeSearchedDefault;
@@ -934,8 +996,8 @@ class User {
 	/**
 	 * Get a given default option value.
 	 *
-	 * @param $opt string
-	 * @return string
+	 * @param $opt \string Name of option to retrieve
+	 * @return \string Default option value
 	 */
 	public static function getDefaultOption( $opt ) {
 		$defOpts = self::getDefaultOptions();
@@ -948,7 +1010,7 @@ class User {
 
 	/**
 	 * Get a list of user toggle names
-	 * @return array
+	 * @return \type{\arrayof{\string}} Array of user toggle names
 	 */
 	static function getToggles() {
 		global $wgContLang;
@@ -961,7 +1023,7 @@ class User {
 	/**
 	 * Get blocking information
 	 * @private
-	 * @param $bFromSlave Bool: specify whether to check slave or master. To
+	 * @param $bFromSlave \bool Whether to check the slave database first. To
 	 *                    improve performance, non-critical checks are done
 	 *                    against slaves. Check when actually saving should be
 	 *                    done against master.
@@ -986,6 +1048,7 @@ class User {
 		
 		$this->mBlockedby = 0;
 		$this->mHideName = 0;
+		$this->mAllowUsertalk = 0;
 		$ip = wfGetIP();
 
 		if ($this->isAllowed( 'ipblock-exempt' ) ) {
@@ -1001,12 +1064,14 @@ class User {
 			$this->mBlockedby = $this->mBlock->mBy;
 			$this->mBlockreason = $this->mBlock->mReason;
 			$this->mHideName = $this->mBlock->mHideName;
+			$this->mAllowUsertalk = $this->mBlock->mAllowUsertalk;
 			if ( $this->isLoggedIn() ) {
 				$this->spreadBlock();
 			}
 		} else {
-			$this->mBlock = null;
-			wfDebug( __METHOD__.": No block.\n" );
+			// Bug 13611: don't remove mBlock here, to allow account creation blocks to 
+			// apply to users. Note that the existence of $this->mBlock is not used to 
+			// check for edit blocks, $this->mBlockedby is instead.
 		}
 
 		# Proxy blocking
@@ -1032,6 +1097,12 @@ class User {
 		wfProfileOut( __METHOD__ );
 	}
 
+	/**
+	 * Whether the given IP is in the SORBS blacklist.
+	 *
+	 * @param $ip \string IP to check
+	 * @return \bool True if blacklisted.
+	 */
 	function inSorbsBlacklist( $ip ) {
 		global $wgEnableSorbs, $wgSorbsUrl;
 
@@ -1039,24 +1110,27 @@ class User {
 			$this->inDnsBlacklist( $ip, $wgSorbsUrl );
 	}
 
+	/**
+	 * Whether the given IP is in a given DNS blacklist.
+	 *
+	 * @param $ip \string IP to check
+	 * @param $base \string URL of the DNS blacklist
+	 * @return \bool True if blacklisted.
+	 */
 	function inDnsBlacklist( $ip, $base ) {
 		wfProfileIn( __METHOD__ );
 
 		$found = false;
 		$host = '';
-		// FIXME: IPv6 ???
-		$m = array();
-		if ( preg_match( '/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/', $ip, $m ) ) {
+		// FIXME: IPv6 ???  (http://bugs.php.net/bug.php?id=33170)
+		if( IP::isIPv4($ip) ) {
 			# Make hostname
-			for ( $i=4; $i>=1; $i-- ) {
-				$host .= $m[$i] . '.';
-			}
-			$host .= $base;
+			$host = "$ip.$base";
 
 			# Send query
 			$ipList = gethostbynamel( $host );
 
-			if ( $ipList ) {
+			if( $ipList ) {
 				wfDebug( "Hostname $host is {$ipList[0]}, it's a proxy says $base!\n" );
 				$found = true;
 			} else {
@@ -1071,7 +1145,7 @@ class User {
 	/**
 	 * Is this user subject to rate limiting?
 	 *
-	 * @return bool
+	 * @return \bool True if rate limited
 	 */
 	public function isPingLimitable() {
 		global $wgRateLimitsExcludedGroups;
@@ -1086,10 +1160,11 @@ class User {
 	 * Primitive rate limits: enforce maximum actions per time period
 	 * to put a brake on flooding.
 	 *
-	 * Note: when using a shared cache like memcached, IP-address
+	 * @note When using a shared cache like memcached, IP-address
 	 * last-hit counters will be shared across wikis.
 	 *
-	 * @return bool true if a rate limiter was tripped
+	 * @param $action \string Action to enforce; 'edit' if unspecified
+	 * @return \bool True if a rate limiter was tripped
 	 */
 	function pingLimiter( $action='edit' ) {
 
@@ -1180,7 +1255,9 @@ class User {
 
 	/**
 	 * Check if user is blocked
-	 * @return bool True if blocked, false otherwise
+	 * 
+	 * @param $bFromSlave \bool Whether to check the slave database instead of the master
+	 * @return \bool True if blocked, false otherwise
 	 */
 	function isBlocked( $bFromSlave = true ) { // hacked from false due to horrible probs on site
 		wfDebug( "User::isBlocked: enter\n" );
@@ -1190,6 +1267,10 @@ class User {
 
 	/**
 	 * Check if user is blocked from editing a particular article
+	 * 
+	 * @param $title      \string Title to check
+	 * @param $bFromSlave \bool   Whether to check the slave database instead of the master
+	 * @return \bool True if blocked, false otherwise
 	 */
 	function isBlockedFrom( $title, $bFromSlave = false ) {
 		global $wgBlockAllowsUTEdit;
@@ -1198,8 +1279,9 @@ class User {
 
 		wfDebug( __METHOD__.": asking isBlocked()\n" );
 		$blocked = $this->isBlocked( $bFromSlave );
+		$allowUsertalk = ($wgBlockAllowsUTEdit ? $this->mAllowUsertalk : false);
 		# If a user's name is suppressed, they cannot make edits anywhere
-		if ( !$this->mHideName && $wgBlockAllowsUTEdit && $title->getText() === $this->getName() &&
+		if ( !$this->mHideName && $allowUsertalk && $title->getText() === $this->getName() &&
 		  $title->getNamespace() == NS_USER_TALK ) {
 			$blocked = false;
 			wfDebug( __METHOD__.": self-talk page, ignoring any blocks\n" );
@@ -1209,8 +1291,8 @@ class User {
 	}
 
 	/**
-	 * Get name of blocker
-	 * @return string name of blocker
+	 * If user is blocked, return the name of the user who placed the block
+	 * @return \string name of blocker
 	 */
 	function blockedBy() {
 		$this->getBlockedStatus();
@@ -1218,16 +1300,74 @@ class User {
 	}
 
 	/**
-	 * Get blocking reason
-	 * @return string Blocking reason
+	 * If user is blocked, return the specified reason for the block
+	 * @return \string Blocking reason
 	 */
 	function blockedFor() {
 		$this->getBlockedStatus();
 		return $this->mBlockreason;
 	}
+	
+	/**
+	 * Check if user is blocked on all wikis.
+	 * Do not use for actual edit permission checks!
+	 * This is intented for quick UI checks.
+	 * 
+	 * @param $ip \type{\string} IP address, uses current client if none given
+	 * @return \type{\bool} True if blocked, false otherwise
+	 */
+	function isBlockedGlobally( $ip = '' ) {
+		if( $this->mBlockedGlobally !== null ) {
+			return $this->mBlockedGlobally;
+		}
+		// User is already an IP?
+		if( IP::isIPAddress( $this->getName() ) ) {
+			$ip = $this->getName();
+		} else if( !$ip ) {
+			$ip = wfGetIP();
+		}
+		$blocked = false;
+		wfRunHooks( 'UserIsBlockedGlobally', array( &$this, $ip, &$blocked ) );
+		$this->mBlockedGlobally = (bool)$blocked;
+		return $this->mBlockedGlobally;
+	}
+	
+	/**
+	 * Check if user account is locked
+	 * 
+	 * @return \type{\bool} True if locked, false otherwise
+	 */
+	function isLocked() {
+		if( $this->mLocked !== null ) {
+			return $this->mLocked;
+		}
+		global $wgAuth;
+		$authUser = $wgAuth->getUserInstance( $this );
+		$this->mLocked = (bool)$authUser->isLocked();
+		return $this->mLocked;
+	}
+	
+	/**
+	 * Check if user account is hidden
+	 * 
+	 * @return \type{\bool} True if hidden, false otherwise
+	 */
+	function isHidden() {
+		if( $this->mHideName !== null ) {
+			return $this->mHideName;
+		}
+		$this->getBlockedStatus();
+		if( !$this->mHideName ) {
+			global $wgAuth;
+			$authUser = $wgAuth->getUserInstance( $this );
+			$this->mHideName = (bool)$authUser->isHidden();
+		}
+		return $this->mHideName;
+	}
 
 	/**
-	 * Get the user ID. Returns 0 if the user is anonymous or nonexistent.
+	 * Get the user's ID.
+	 * @return \int The user's ID; 0 if the user is anonymous or nonexistent
 	 */
 	function getId() {
 		if( $this->mId === null and $this->mName !== null
@@ -1242,7 +1382,8 @@ class User {
 	}
 
 	/**
-	 * Set the user and reload all fields according to that ID
+	 * Set the user and reload all fields according to a given ID
+	 * @param $v \int User ID to reload
 	 */
 	function setId( $v ) {
 		$this->mId = $v;
@@ -1250,7 +1391,8 @@ class User {
 	}
 
 	/**
-	 * Get the user name, or the IP for anons
+	 * Get the user name, or the IP of an anonymous user
+	 * @return \string User's name or IP address
 	 */
 	function getName() {
 		if ( !$this->mDataLoaded && $this->mFrom == 'name' ) {
@@ -1275,8 +1417,9 @@ class User {
 	 * address for an anonymous user to something other than the current
 	 * remote IP.
 	 *
-	 * User::newFromName() has rougly the same function, when the named user
+	 * @note User::newFromName() has rougly the same function, when the named user
 	 * does not exist.
+	 * @param $str \string New user name to set
 	 */
 	function setName( $str ) {
 		$this->load();
@@ -1284,13 +1427,17 @@ class User {
 	}
 
 	/**
-	 * Return the title dbkey form of the name, for eg user pages.
-	 * @return string
+	 * Get the user's name escaped by underscores.
+	 * @return \string Username escaped by underscores.
 	 */
 	function getTitleKey() {
 		return str_replace( ' ', '_', $this->getName() );
 	}
 
+	/**
+	 * Check if the user has new messages.
+	 * @return \bool True if the user has new messages
+	 */
 	function getNewtalk() {
 		$this->load();
 
@@ -1322,6 +1469,7 @@ class User {
 
 	/**
 	 * Return the talk page(s) this user has new messages on.
+	 * @return \type{\arrayof{\string}} Array of page URLs
 	 */
 	function getNewMessageLinks() {
 		$talks = array();
@@ -1337,13 +1485,13 @@ class User {
 
 
 	/**
-	 * Perform a user_newtalk check, uncached.
-	 * Use getNewtalk for a cached check.
+	 * Internal uncached check for new messages
 	 *
-	 * @param $field string
-	 * @param $id mixed
-	 * @param $fromMaster Bool: true to fetch from the master, false for a slave
-	 * @return bool
+	 * @see getNewtalk()
+	 * @param $field \string 'user_ip' for anonymous users, 'user_id' otherwise
+	 * @param $id \types{\string,\int} User's IP address for anonymous users, User ID otherwise
+	 * @param $fromMaster \bool true to fetch from the master, false for a slave
+	 * @return \bool True if the user has new messages
 	 * @private
 	 */
 	function checkNewtalk( $field, $id, $fromMaster = false ) {
@@ -1358,9 +1506,10 @@ class User {
 	}
 
 	/**
-	 * Add or update the
-	 * @param $field string
-	 * @param $id mixed
+	 * Add or update the new messages flag
+	 * @param $field \string 'user_ip' for anonymous users, 'user_id' otherwise
+	 * @param $id \types{\string,\int} User's IP address for anonymous users, User ID otherwise
+	 * @return \bool True if successful, false otherwise
 	 * @private
 	 */
 	function updateNewtalk( $field, $id ) {
@@ -1380,8 +1529,9 @@ class User {
 
 	/**
 	 * Clear the new messages flag for the given user
-	 * @param $field string
-	 * @param $id mixed
+	 * @param $field \string 'user_ip' for anonymous users, 'user_id' otherwise
+	 * @param $id \types{\string,\int} User's IP address for anonymous users, User ID otherwise
+	 * @return \bool True if successful, false otherwise
 	 * @private
 	 */
 	function deleteNewtalk( $field, $id ) {
@@ -1400,7 +1550,7 @@ class User {
 
 	/**
 	 * Update the 'You have new messages!' status.
-	 * @param $val bool
+	 * @param $val \bool Whether the user has new messages
 	 */
 	function setNewtalk( $val ) {
 		if( wfReadOnly() ) {
@@ -1439,6 +1589,7 @@ class User {
 	/**
 	 * Generate a current or new-future timestamp to be stored in the
 	 * user_touched field when we update things.
+	 * @return \string Timestamp in TS_MW format
 	 */
 	private static function newTouchedTimestamp() {
 		global $wgClockSkewFudge;
@@ -1453,6 +1604,7 @@ class User {
 	 * Called implicitly from invalidateCache() and saveSettings().
 	 */
 	private function clearSharedCache() {
+		$this->load();
 		if( $this->mId ) {
 			global $wgMemc;
 			$wgMemc->delete( wfMemcKey( 'user', 'id', $this->mId ) );
@@ -1479,13 +1631,25 @@ class User {
 		}
 	}
 
+	/**
+	 * Validate the cache for this account.
+	 * @param $timestamp \string A timestamp in TS_MW format
+	 */
 	function validateCache( $timestamp ) {
 		$this->load();
 		return ($timestamp >= $this->mTouched);
 	}
 
 	/**
-	 * Set the password and reset the random token
+	 * Get the user touched timestamp
+	 */
+	function getTouched() {
+		$this->load();
+		return $this->mTouched;
+	}
+
+	/**
+	 * Set the password and reset the random token.
 	 * Calls through to authentication plugin if necessary;
 	 * will have no effect if the auth plugin refuses to
 	 * pass the change through or if the legal password
@@ -1495,7 +1659,7 @@ class User {
 	 * wipes it, so the account cannot be logged in until
 	 * a new password is set, for instance via e-mail.
 	 *
-	 * @param $str string
+	 * @param $str \string New password to set
 	 * @throws PasswordError on failure
 	 */
 	function setPassword( $str ) {
@@ -1523,10 +1687,9 @@ class User {
 	}
 
 	/**
-	 * Set the password and reset the random token no matter
-	 * what.
+	 * Set the password and reset the random token unconditionally.
 	 *
-	 * @param $str string
+	 * @param $str \string New password to set
 	 */
 	function setInternalPassword( $str ) {
 		$this->load();
@@ -1542,6 +1705,10 @@ class User {
 		$this->mNewpassTime = null;
 	}
 	
+	/**
+	 * Get the user's current token.
+	 * @return \string Token
+	 */
 	function getToken() {
 		$this->load();
 		return $this->mToken;
@@ -1550,6 +1717,8 @@ class User {
 	/**
 	 * Set the random token (used for persistent authentication)
 	 * Called from loadDefaults() among other places.
+	 *
+	 * @param $token \string If specified, set the token to this value
 	 * @private
 	 */
 	function setToken( $token = false ) {
@@ -1568,7 +1737,13 @@ class User {
 			$this->mToken = $token;
 		}
 	}
-
+	
+	/**
+	 * Set the cookie password
+	 *
+	 * @param $str \string New cookie password
+	 * @private
+	 */
 	function setCookiePassword( $str ) {
 		$this->load();
 		$this->mCookiePassword = md5( $str );
@@ -1576,7 +1751,9 @@ class User {
 
 	/**
 	 * Set the password for a password reminder or new account email
-	 * Sets the user_newpass_time field if $throttle is true
+	 *
+	 * @param $str \string New password to set
+	 * @param $throttle \bool If true, reset the throttle timestamp to the present
 	 */
 	function setNewpassword( $str, $throttle = true ) {
 		$this->load();
@@ -1587,8 +1764,9 @@ class User {
 	}
 
 	/**
-	 * Returns true if a password reminder email has already been sent within
-	 * the last $wgPasswordReminderResendTime hours
+	 * Has password reminder email been sent within the last 
+	 * $wgPasswordReminderResendTime hours?
+	 * @return \bool True or false
 	 */
 	function isPasswordReminderThrottled() {
 		global $wgPasswordReminderResendTime;
@@ -1600,38 +1778,62 @@ class User {
 		return time() < $expiry;
 	}
 
+	/**
+	 * Get the user's e-mail address
+	 * @return \string User's email address
+	 */
 	function getEmail() {
 		$this->load();
 		wfRunHooks( 'UserGetEmail', array( $this, &$this->mEmail ) );
 		return $this->mEmail;
 	}
 
+	/**
+	 * Get the timestamp of the user's e-mail authentication
+	 * @return \string TS_MW timestamp
+	 */
 	function getEmailAuthenticationTimestamp() {
 		$this->load();
 		wfRunHooks( 'UserGetEmailAuthenticationTimestamp', array( $this, &$this->mEmailAuthenticated ) );
 		return $this->mEmailAuthenticated;
 	}
 
+	/**
+	 * Set the user's e-mail address
+	 * @param $str \string New e-mail address
+	 */
 	function setEmail( $str ) {
 		$this->load();
 		$this->mEmail = $str;
 		wfRunHooks( 'UserSetEmail', array( $this, &$this->mEmail ) );
 	}
 
+	/**
+	 * Get the user's real name
+	 * @return \string User's real name
+	 */
 	function getRealName() {
 		$this->load();
 		return $this->mRealName;
 	}
 
+	/**
+	 * Set the user's real name
+	 * @param $str \string New real name
+	 */
 	function setRealName( $str ) {
 		$this->load();
 		$this->mRealName = $str;
 	}
 
 	/**
-	 * @param $oname String: the option to check
-	 * @param $defaultOverride String: A default value returned if the option does not exist
-	 * @return string
+	 * Get the user's current setting for a given option.
+	 *
+	 * @param $oname \string The option to check
+	 * @param $defaultOverride \string A default value returned if the option does not exist
+	 * @return \string User's current value for the option
+	 * @see getBoolOption()
+	 * @see getIntOption()
 	 */
 	function getOption( $oname, $defaultOverride = '' ) {
 		$this->load();
@@ -1649,46 +1851,41 @@ class User {
 			return $defaultOverride;
 		}
 	}
-
-	/**
-	 * Get the user's date preference, including some important migration for
-	 * old user rows.
-	 */
-	function getDatePreference() {
-		if ( is_null( $this->mDatePreference ) ) {
-			global $wgLang;
-			$value = $this->getOption( 'date' );
-			$map = $wgLang->getDatePreferenceMigrationMap();
-			if ( isset( $map[$value] ) ) {
-				$value = $map[$value];
-			}
-			$this->mDatePreference = $value;
-		}
-		return $this->mDatePreference;
-	}
-
+	
 	/**
-	 * @param $oname String: the option to check
-	 * @return bool False if the option is not selected, true if it is
+	 * Get the user's current setting for a given option, as a boolean value.
+	 *
+	 * @param $oname \string The option to check
+	 * @return \bool User's current value for the option
+	 * @see getOption()
 	 */
 	function getBoolOption( $oname ) {
 		return (bool)$this->getOption( $oname );
 	}
 
+	
 	/**
-	 * Get an option as an integer value from the source string.
-	 * @param $oname String: the option to check
-	 * @param $default Int: optional value to return if option is unset/blank.
-	 * @return int
+	 * Get the user's current setting for a given option, as a boolean value.
+	 *
+	 * @param $oname \string The option to check
+	 * @param $defaultOverride \int A default value returned if the option does not exist
+	 * @return \int User's current value for the option
+	 * @see getOption()
 	 */
-	function getIntOption( $oname, $default=0 ) {
+	function getIntOption( $oname, $defaultOverride=0 ) {
 		$val = $this->getOption( $oname );
 		if( $val == '' ) {
-			$val = $default;
+			$val = $defaultOverride;
 		}
 		return intval( $val );
 	}
 
+	/**
+	 * Set the given option for a user.
+	 *
+	 * @param $oname \string The option to set
+	 * @param $val \mixed New value to set
+	 */
 	function setOption( $oname, $val ) {
 		$this->load();
 		if ( is_null( $this->mOptions ) ) {
@@ -1713,6 +1910,28 @@ class User {
 		$this->mOptions[$oname] = $val;
 	}
 
+	/**
+	 * Get the user's preferred date format.
+	 * @return \string User's preferred date format
+	 */
+	function getDatePreference() {
+		// Important migration for old data rows
+		if ( is_null( $this->mDatePreference ) ) {
+			global $wgLang;
+			$value = $this->getOption( 'date' );
+			$map = $wgLang->getDatePreferenceMigrationMap();
+			if ( isset( $map[$value] ) ) {
+				$value = $map[$value];
+			}
+			$this->mDatePreference = $value;
+		}
+		return $this->mDatePreference;
+	}
+
+	/**
+	 * Get the permissions this user has.
+	 * @return \type{\arrayof{\string}} Array of permission names
+	 */
 	function getRights() {
 		if ( is_null( $this->mRights ) ) {
 			$this->mRights = self::getGroupPermissions( $this->getEffectiveGroups() );
@@ -1726,7 +1945,7 @@ class User {
 	/**
 	 * Get the list of explicit group memberships this user has.
 	 * The implicit * and user groups are not included.
-	 * @return array of strings
+	 * @return \type{\arrayof{\string}} Array of internal group names
 	 */
 	function getGroups() {
 		$this->load();
@@ -1737,8 +1956,8 @@ class User {
 	 * Get the list of implicit group memberships this user has.
 	 * This includes all explicit groups, plus 'user' if logged in,
 	 * '*' for all accounts and autopromoted groups
-	 * @param $recache Boolean: don't use the cache
-	 * @return array of strings
+	 * @param $recache \bool Whether to avoid the cache
+	 * @return \type{\arrayof{\string}} Array of internal group names
 	 */
 	function getEffectiveGroups( $recache = false ) {
 		if ( $recache || is_null( $this->mEffectiveGroups ) ) {
@@ -1759,7 +1978,10 @@ class User {
 		return $this->mEffectiveGroups;
 	}
 
-	/* Return the edit count for the user. This is where User::edits should have been */
+	/**
+	 * Get the user's edit count.
+	 * @return \int User'e edit count
+	 */
 	function getEditCount() {
 		if ($this->mId) {
 			if ( !isset( $this->mEditCount ) ) {
@@ -1776,7 +1998,7 @@ class User {
 	/**
 	 * Add the user to the given group.
 	 * This takes immediate effect.
-	 * @param $group string
+	 * @param $group \string Name of the group to add
 	 */
 	function addGroup( $group ) {
 		$dbw = wfGetDB( DB_MASTER );
@@ -1800,7 +2022,7 @@ class User {
 	/**
 	 * Remove the user from the given group.
 	 * This takes immediate effect.
-	 * @param $group string
+	 * @param $group \string Name of the group to remove
 	 */
 	function removeGroup( $group ) {
 		$this->load();
@@ -1821,27 +2043,24 @@ class User {
 
 
 	/**
-	 * A more legible check for non-anonymousness.
-	 * Returns true if the user is not an anonymous visitor.
-	 *
-	 * @return bool
+	 * Get whether the user is logged in
+	 * @return \bool True or false
 	 */
 	function isLoggedIn() {
 		return $this->getID() != 0;
 	}
 
 	/**
-	 * A more legible check for anonymousness.
-	 * Returns true if the user is an anonymous visitor.
-	 *
-	 * @return bool
+	 * Get whether the user is anonymous
+	 * @return \bool True or false
 	 */
 	function isAnon() {
 		return !$this->isLoggedIn();
 	}
 
 	/**
-	 * Whether the user is a bot
+	 * Get whether the user is a bot
+	 * @return \bool True or false
 	 * @deprecated
 	 */
 	function isBot() {
@@ -1851,8 +2070,8 @@ class User {
 
 	/**
 	 * Check if user is allowed to access a feature / make an action
-	 * @param $action String: action to be checked
-	 * @return boolean True: action is allowed, False: action should not be allowed
+	 * @param $action \string action to be checked
+	 * @return \bool True if action is allowed, else false
 	 */
 	function isAllowed($action='') {
 		if ( $action === '' )
@@ -1866,7 +2085,7 @@ class User {
 
 	/**
 	* Check whether to enable recent changes patrol features for this user
-	* @return bool
+	* @return \bool True or false
 	*/
 	public function useRCPatrol() {
 		global $wgUseRCPatrol;
@@ -1874,8 +2093,8 @@ class User {
 	}
 
 	/**
-	* Check whether to enable recent changes patrol features for this user
-	* @return bool
+	* Check whether to enable new pages patrol features for this user
+	* @return \bool True or false
 	*/
 	public function useNPPatrol() {
 		global $wgUseRCPatrol, $wgUseNPPatrol;
@@ -1883,31 +2102,34 @@ class User {
 	}
 
 	/**
-	 * Load a skin if it doesn't exist or return it
+	 * Get the current skin, loading it if required
+	 * @return \type{Skin} Current skin
 	 * @todo FIXME : need to check the old failback system [AV]
 	 */
 	function &getSkin() {
-		global $wgRequest;
+		global $wgRequest, $wgAllowUserSkin, $wgDefaultSkin;
 		if ( ! isset( $this->mSkin ) ) {
 			wfProfileIn( __METHOD__ );
 
-			# get the user skin
-			$userSkin = $this->getOption( 'skin' );
-			$userSkin = $wgRequest->getVal('useskin', $userSkin);
-
+			if( $wgAllowUserSkin ) {
+				# get the user skin
+				$userSkin = $this->getOption( 'skin' );
+				$userSkin = $wgRequest->getVal('useskin', $userSkin);
+			} else {
+				# if we're not allowing users to override, then use the default
+				$userSkin = $wgDefaultSkin;
+			}
+			
 			$this->mSkin =& Skin::newFromKey( $userSkin );
 			wfProfileOut( __METHOD__ );
 		}
 		return $this->mSkin;
 	}
 
-	/**#@+
-	 * @param $title Title: article title to look at
-	 */
-
 	/**
-	 * Check watched status of an article
-	 * @return bool True if article is watched
+	 * Check the watched status of an article.
+	 * @param $title \type{Title} Title of the article to look at
+	 * @return \bool True if article is watched
 	 */
 	function isWatched( $title ) {
 		$wl = WatchedItem::fromUserTitle( $this, $title );
@@ -1915,7 +2137,8 @@ class User {
 	}
 
 	/**
-	 * Watch an article
+	 * Watch an article.
+	 * @param $title \type{Title} Title of the article to look at
 	 */
 	function addWatch( $title ) {
 		$wl = WatchedItem::fromUserTitle( $this, $title );
@@ -1924,7 +2147,8 @@ class User {
 	}
 
 	/**
-	 * Stop watching an article
+	 * Stop watching an article.
+	 * @param $title \type{Title} Title of the article to look at
 	 */
 	function removeWatch( $title ) {
 		$wl = WatchedItem::fromUserTitle( $this, $title );
@@ -1936,6 +2160,7 @@ class User {
 	 * Clear the user's notification timestamp for the given title.
 	 * If e-notif e-mails are on, they will receive notification mails on
 	 * the next change of the page if it's watched etc.
+	 * @param $title \type{Title} Title of the article to look at
 	 */
 	function clearNotification( &$title ) {
 		global $wgUser, $wgUseEnotif, $wgShowUpdatedMarker;
@@ -1991,14 +2216,12 @@ class User {
 		}
 	}
 
-	/**#@-*/
-
 	/**
 	 * Resets all of the given user's page-change notification timestamps.
 	 * If e-notif e-mails are on, they will receive notification mails on
 	 * the next change of any watched page.
 	 *
-	 * @param $currentUser Int: user ID number
+	 * @param $currentUser \int User ID
 	 */
 	function clearAllNotifications( $currentUser ) {
 		global $wgUseEnotif, $wgShowUpdatedMarker;
@@ -2021,8 +2244,9 @@ class User {
 	}
 
 	/**
+	 * Encode this user's options as a string
+	 * @return \string Encoded options
 	 * @private
-	 * @return string Encoding options
 	 */
 	function encodeOptions() {
 		$this->load();
@@ -2038,6 +2262,8 @@ class User {
 	}
 
 	/**
+	 * Set this user's options from an encoded string
+	 * @param $str \string Encoded options to import
 	 * @private
 	 */
 	function decodeOptions( $str ) {
@@ -2051,46 +2277,30 @@ class User {
 		}
 	}
 	
+	/**
+	 * Set a cookie on the user's client. Wrapper for 
+	 * WebResponse::setCookie
+	 * @param $name \string Name of the cookie to set
+	 * @param $value \string Value to set
+	 * @param $exp \int Expiration time, as a UNIX time value; 
+	 *                   if 0 or not specified, use the default $wgCookieExpiration
+	 */
 	protected function setCookie( $name, $value, $exp=0 ) {
-		global $wgCookiePrefix,$wgCookieDomain,$wgCookieSecure,$wgCookieExpiration, $wgCookieHttpOnly;
-		if( $exp == 0 ) {
-			$exp = time() + $wgCookieExpiration;
-		}
-		$httpOnlySafe = wfHttpOnlySafe();
-		wfDebugLog( 'cookie',
-			'setcookie: "' . implode( '", "',
-				array(
-					$wgCookiePrefix . $name,
-					$value,
-					$exp,
-					'/',
-					$wgCookieDomain,
-					$wgCookieSecure,
-					$httpOnlySafe && $wgCookieHttpOnly ) ) . '"' );
-		if( $httpOnlySafe && isset( $wgCookieHttpOnly ) ) {
-			setcookie( $wgCookiePrefix . $name,
-				$value,
-				$exp,
-				'/',
-				$wgCookieDomain,
-				$wgCookieSecure,
-				$wgCookieHttpOnly );
-		} else {
-			// setcookie() fails on PHP 5.1 if you give it future-compat paramters.
-			// stab stab!
-			setcookie( $wgCookiePrefix . $name,
-				$value,
-				$exp,
-				'/',
-				$wgCookieDomain,
-				$wgCookieSecure );
-		}
+		global $wgRequest;
+		$wgRequest->response()->setcookie( $name, $value, $exp );
 	}
 	
+	/**
+	 * Clear a cookie on the user's client
+	 * @param $name \string Name of the cookie to clear
+	 */
 	protected function clearCookie( $name ) {
 		$this->setCookie( $name, '', time() - 86400 );
 	}
 
+	/**
+	 * Set the default cookies for this session on the user's client.
+	 */
 	function setCookies() {
 		$this->load();
 		if ( 0 == $this->mId ) return;
@@ -2110,7 +2320,10 @@ class User {
 		}
 		
 		wfRunHooks( 'UserSetCookies', array( $this, &$session, &$cookies ) );
-		$_SESSION = $session + $_SESSION;
+		#check for null, since the hook could cause a null value 
+		if ( !is_null( $session ) && isset( $_SESSION ) ){
+			$_SESSION = $session + $_SESSION;
+		}
 		foreach ( $cookies as $name => $value ) {
 			if ( $value === false ) {
 				$this->clearCookie( $name );
@@ -2121,7 +2334,7 @@ class User {
 	}
 
 	/**
-	 * Logout user.
+	 * Log this user out.
 	 */
 	function logout() {
 		global $wgUser;
@@ -2131,8 +2344,9 @@ class User {
 	}
 
 	/**
-	 * Really logout user
-	 * Clears the cookies and session, resets the instance cache
+	 * Clear the user's cookies and session, and reset the instance cache.
+	 * @private
+	 * @see logout()
 	 */
 	function doLogout() {
 		$this->clearInstanceCache( 'defaults' );
@@ -2147,7 +2361,7 @@ class User {
 	}
 
 	/**
-	 * Save object settings into database
+	 * Save this user's settings into the database.
 	 * @todo Only rarely do all these fields need to be set!
 	 */
 	function saveSettings() {
@@ -2178,10 +2392,11 @@ class User {
 		);
 		wfRunHooks( 'UserSaveSettings', array( $this ) );
 		$this->clearSharedCache();
+		$this->getUserPage()->invalidateCache();
 	}
 
 	/**
-	 * Checks if a user with the given name exists, returns the ID.
+	 * If only this user's username is known, and it exists, return the user ID.
 	 */
 	function idForName() {
 		$s = trim( $this->getName() );
@@ -2198,18 +2413,18 @@ class User {
 	/**
 	 * Add a user to the database, return the user object
 	 *
-	 * @param $name String: the user's name
-	 * @param $params Associative array of non-default parameters to save to the database:
-	 *     password             The user's password. Password logins will be disabled if this is omitted.
-	 *     newpassword          A temporary password mailed to the user
-	 *     email                The user's email address
-	 *     email_authenticated  The email authentication timestamp
-	 *     real_name            The user's real name
-	 *     options              An associative array of non-default options
-	 *     token                Random authentication token. Do not set.
-	 *     registration         Registration timestamp. Do not set.
+	 * @param $name \string Username to add
+	 * @param $params \type{\arrayof{\string}} Non-default parameters to save to the database:
+	 *   - password             The user's password. Password logins will be disabled if this is omitted.
+	 *   - newpassword          A temporary password mailed to the user
+	 *   - email                The user's email address
+	 *   - email_authenticated  The email authentication timestamp
+	 *   - real_name            The user's real name
+	 *   - options              An associative array of non-default options
+	 *   - token                Random authentication token. Do not set.
+	 *   - registration         Registration timestamp. Do not set.
 	 *
-	 * @return User object, or null if the username already exists
+	 * @return \type{User} A new User object, or null if the username already exists
 	 */
 	static function createNew( $name, $params = array() ) {
 		$user = new User;
@@ -2247,7 +2462,7 @@ class User {
 	}
 
 	/**
-	 * Add an existing user object to the database
+	 * Add this existing user object to the database
 	 */
 	function addToDatabase() {
 		$this->load();
@@ -2271,13 +2486,13 @@ class User {
 		);
 		$this->mId = $dbw->insertId();
 
-		# Clear instance cache other than user table data, which is already accurate
+		// Clear instance cache other than user table data, which is already accurate
 		$this->clearInstanceCache();
 	}
 
 	/**
-	 * If the (non-anonymous) user is blocked, this function will block any IP address
-	 * that they successfully log on from.
+	 * If this (non-anonymous) user is blocked, block any IP address
+	 * they've successfully logged in from.
 	 */
 	function spreadBlock() {
 		wfDebug( __METHOD__."()\n" );
@@ -2306,10 +2521,10 @@ class User {
 	 * which will give them a chance to modify this key based on their own
 	 * settings.
 	 *
-	 * @return string
+	 * @return \string Page rendering hash
 	 */
 	function getPageRenderingHash() {
-		global $wgContLang, $wgUseDynamicDates, $wgLang;
+		global $wgUseDynamicDates, $wgRenderHashAppend, $wgLang, $wgContLang;
 		if( $this->mHash ){
 			return $this->mHash;
 		}
@@ -2329,6 +2544,8 @@ class User {
 		$extra = $wgContLang->getExtraHashOptions();
 		$confstr .= $extra;
 
+		$confstr .= $wgRenderHashAppend;
+
 		// Give a chance for extensions to modify the hash, if they have
 		// extra options or other effects on the parser cache.
 		wfRunHooks( 'PageRenderingHash', array( &$confstr ) );
@@ -2339,21 +2556,28 @@ class User {
 		return $confstr;
 	}
 
+	/**
+	 * Get whether the user is explicitly blocked from account creation.
+	 * @return \bool True if blocked
+	 */
 	function isBlockedFromCreateAccount() {
 		$this->getBlockedStatus();
 		return $this->mBlock && $this->mBlock->mCreateAccount;
 	}
 
 	/**
-	 * Determine if the user is blocked from using Special:Emailuser.
-	 *
-	 * @return boolean
+	 * Get whether the user is blocked from using Special:Emailuser.
+	 * @return \bool True if blocked
 	 */
 	function isBlockedFromEmailuser() {
 		$this->getBlockedStatus();
 		return $this->mBlock && $this->mBlock->mBlockEmail;
 	}
 
+	/**
+	 * Get whether the user is allowed to create an account.
+	 * @return \bool True if allowed
+	 */
 	function isAllowedToCreateAccount() {
 		return $this->isAllowed( 'createaccount' ) && !$this->isBlockedFromCreateAccount();
 	}
@@ -2368,7 +2592,7 @@ class User {
 	/**
 	 * Get this user's personal page title.
 	 *
-	 * @return Title
+	 * @return \type{Title} User's personal page title
 	 */
 	function getUserPage() {
 		return Title::makeTitle( NS_USER, $this->getName() );
@@ -2377,7 +2601,7 @@ class User {
 	/**
 	 * Get this user's talk page title.
 	 *
-	 * @return Title
+	 * @return \type{Title} User's talk page title
 	 */
 	function getTalkPage() {
 		$title = $this->getUserPage();
@@ -2385,6 +2609,8 @@ class User {
 	}
 
 	/**
+	 * Get the maximum valid user ID.
+	 * @return \int User ID
 	 * @static
 	 */
 	function getMaxID() {
@@ -2401,7 +2627,7 @@ class User {
 	/**
 	 * Determine whether the user is a newbie. Newbies are either
 	 * anonymous IPs, or the most recently created accounts.
-	 * @return bool True if it is a newbie.
+	 * @return \bool True if the user is a newbie
 	 */
 	function isNewbie() {
 		return !$this->isAllowed( 'autoconfirmed' );
@@ -2411,7 +2637,7 @@ class User {
 	 * Is the user active? We check to see if they've made at least
 	 * X number of edits in the last Y days.
 	 * 
-	 * @return bool true if the user is active, false if not
+	 * @return \bool True if the user is active, false if not.
 	 */
 	public function isActiveEditor() {
 		global $wgActiveUserEditCount, $wgActiveUserDays;
@@ -2435,8 +2661,8 @@ class User {
 
 	/**
 	 * Check to see if the given clear-text password is one of the accepted passwords
-	 * @param $password String: user password.
-	 * @return bool True if the given password is correct otherwise False.
+	 * @param $password \string user password.
+	 * @return \bool True if the given password is correct, otherwise False.
 	 */
 	function checkPassword( $password ) {
 		global $wgAuth;
@@ -2476,7 +2702,7 @@ class User {
 	/**
 	 * Check if the given clear-text password matches the temporary password
 	 * sent by e-mail for password reset operations.
-	 * @return bool
+	 * @return \bool True if matches, false otherwise
 	 */
 	function checkTemporaryPassword( $plaintext ) {
 		return self::comparePasswords( $this->mNewpassword, $plaintext, $this->getId() );
@@ -2488,9 +2714,8 @@ class User {
 	 * login credentials aren't being hijacked with a foreign form
 	 * submission.
 	 *
-	 * @param $salt Mixed: optional function-specific data for hash.
-	 *                     Use a string or an array of strings.
-	 * @return string
+	 * @param $salt \types{\string,\arrayof{\string}} Optional function-specific data for hashing
+	 * @return \string The new edit token
 	 */
 	function editToken( $salt = '' ) {
 		if ( $this->isAnon() ) {
@@ -2510,9 +2735,10 @@ class User {
 	}
 
 	/**
-	 * Generate a hex-y looking random token for various uses.
-	 * Could be made more cryptographically sure if someone cares.
-	 * @return string
+	 * Generate a looking random token for various uses.
+	 *
+	 * @param $salt \string Optional salt value
+	 * @return \string The new random token
 	 */
 	function generateToken( $salt = '' ) {
 		$token = dechex( mt_rand() ) . dechex( mt_rand() );
@@ -2525,9 +2751,9 @@ class User {
 	 * user's own login session, not a form submission from a third-party
 	 * site.
 	 *
-	 * @param $val String: the input value to compare
-	 * @param $salt String: optional function-specific data for hash
-	 * @return bool
+	 * @param $val \string Input value to compare
+	 * @param $salt \string Optional function-specific data for hashing
+	 * @return \bool Whether the token matches
 	 */
 	function matchEditToken( $val, $salt = '' ) {
 		$sessionToken = $this->editToken( $salt );
@@ -2538,7 +2764,12 @@ class User {
 	}
 
 	/**
-	 * Check whether the edit token is fine except for the suffix
+	 * Check given value against the token value stored in the session,
+	 * ignoring the suffix.
+	 *
+	 * @param $val \string Input value to compare
+	 * @param $salt \string Optional function-specific data for hashing
+	 * @return \bool Whether the token matches
 	 */
 	function matchEditTokenNoSuffix( $val, $salt = '' ) {
 		$sessionToken = $this->editToken( $salt );
@@ -2549,10 +2780,7 @@ class User {
 	 * Generate a new e-mail confirmation token and send a confirmation/invalidation
 	 * mail to the user's given address.
 	 *
-	 * Calls saveSettings() internally; as it has side effects, not committing changes
-	 * would be pretty silly.
-	 *
-	 * @return mixed True on success, a WikiError object on failure.
+	 * @return \types{\bool,\type{WikiError}} True on success, a WikiError object on failure.
 	 */
 	function sendConfirmationMail() {
 		global $wgLang;
@@ -2575,11 +2803,11 @@ class User {
 	 * Send an e-mail to this user's account. Does not check for
 	 * confirmed status or validity.
 	 *
-	 * @param $subject string
-	 * @param $body string
-	 * @param $from string: optional from address; default $wgPasswordSender will be used otherwise.
-	 * @param $replyto string
-	 * @return mixed True on success, a WikiError object on failure.
+	 * @param $subject \string Message subject
+	 * @param $body \string Message body
+	 * @param $from \string Optional From address; if unspecified, default $wgPasswordSender will be used
+	 * @param $replyto \string Reply-To address
+	 * @return \types{\bool,\type{WikiError}} True on success, a WikiError object on failure
 	 */
 	function sendMail( $subject, $body, $from = null, $replyto = null ) {
 		if( is_null( $from ) ) {
@@ -2594,13 +2822,13 @@ class User {
 
 	/**
 	 * Generate, store, and return a new e-mail confirmation code.
-	 * A hash (unsalted since it's used as a key) is stored.
+	 * A hash (unsalted, since it's used as a key) is stored.
 	 *
-	 * Call saveSettings() after calling this function to commit
+	 * @note Call saveSettings() after calling this function to commit
 	 * this change to the database.
 	 *
-	 * @param &$expiration mixed output: accepts the expiration time
-	 * @return string
+	 * @param[out] &$expiration \mixed Accepts the expiration time
+	 * @return \string New token
 	 * @private
 	 */
 	function confirmationToken( &$expiration ) {
@@ -2617,8 +2845,8 @@ class User {
 
 	/**
 	* Return a URL the user can use to confirm their email address.
-	 * @param $token accepts the email confirmation token
-	 * @return string
+	 * @param $token \string Accepts the email confirmation token
+	 * @return \string New token URL
 	 * @private
 	 */
 	function confirmationTokenUrl( $token ) {
@@ -2626,8 +2854,8 @@ class User {
 	}
 	/**
 	 * Return a URL the user can use to invalidate their email address.
-	 * @param $token accepts the email confirmation token
-	 * @return string
+	 * @param $token \string Accepts the email confirmation token
+	 * @return \string New token URL
 	 * @private
 	 */
 	function invalidationTokenUrl( $token ) {
@@ -2639,10 +2867,14 @@ class User {
 	 * This uses $wgArticlePath directly as a quickie hack to use the
 	 * hardcoded English names of the Special: pages, for ASCII safety.
 	 *
-	 * Since these URLs get dropped directly into emails, using the
+	 * @note Since these URLs get dropped directly into emails, using the
 	 * short English names avoids insanely long URL-encoded links, which
 	 * also sometimes can get corrupted in some browsers/mailers
 	 * (bug 6957 with Gmail and Internet Explorer).
+	 *
+	 * @param $page \string Special page
+	 * @param $token \string Token
+	 * @return \string Formatted URL
 	 */
 	protected function getTokenUrl( $page, $token ) {
 		global $wgArticlePath;
@@ -2656,7 +2888,7 @@ class User {
 	/**
 	 * Mark the e-mail address confirmed.
 	 *
-	 * Call saveSettings() after calling this function to commit the change.
+	 * @note Call saveSettings() after calling this function to commit the change.
 	 */
 	function confirmEmail() {
 		$this->setEmailAuthenticationTimestamp( wfTimestampNow() );
@@ -2664,10 +2896,10 @@ class User {
 	}
 
 	/**
-	 * Invalidate the user's email confirmation, unauthenticate the email
-	 * if it was already confirmed.
+	 * Invalidate the user's e-mail confirmation, and unauthenticate the e-mail
+	 * address if it was already confirmed.
 	 *
-	 * Call saveSettings() after calling this function to commit the change.
+	 * @note Call saveSettings() after calling this function to commit the change.
 	 */
 	function invalidateEmail() {
 		$this->load();
@@ -2677,6 +2909,10 @@ class User {
 		return true;
 	}
 
+	/**
+	 * Set the e-mail authentication timestamp.
+	 * @param $timestamp \string TS_MW timestamp
+	 */
 	function setEmailAuthenticationTimestamp( $timestamp ) {
 		$this->load();
 		$this->mEmailAuthenticated = $timestamp;
@@ -2686,9 +2922,13 @@ class User {
 	/**
 	 * Is this user allowed to send e-mails within limits of current
 	 * site configuration?
-	 * @return bool
+	 * @return \bool True if allowed
 	 */
 	function canSendEmail() {
+		global $wgEnableEmail, $wgEnableUserEmail;
+		if( !$wgEnableEmail || !$wgEnableUserEmail ) {
+			return false;
+		}
 		$canSend = $this->isEmailConfirmed();
 		wfRunHooks( 'UserCanSendEmail', array( &$this, &$canSend ) );
 		return $canSend;
@@ -2697,7 +2937,7 @@ class User {
 	/**
 	 * Is this user allowed to receive e-mails within limits of current
 	 * site configuration?
-	 * @return bool
+	 * @return \bool True if allowed
 	 */
 	function canReceiveEmail() {
 		return $this->isEmailConfirmed() && !$this->getOption( 'disablemail' );
@@ -2707,11 +2947,11 @@ class User {
 	 * Is this user's e-mail address valid-looking and confirmed within
 	 * limits of the current site configuration?
 	 *
-	 * If $wgEmailAuthentication is on, this may require the user to have
+	 * @note If $wgEmailAuthentication is on, this may require the user to have
 	 * confirmed their address by returning a code or using a password
 	 * sent to the address from the wiki.
 	 *
-	 * @return bool
+	 * @return \bool True if confirmed
 	 */
 	function isEmailConfirmed() {
 		global $wgEmailAuthentication;
@@ -2731,8 +2971,8 @@ class User {
 	}
 
 	/**
-	 * Return true if there is an outstanding request for e-mail confirmation.
-	 * @return bool
+	 * Check whether there is an outstanding request for e-mail confirmation.
+	 * @return \bool True if pending
 	 */
 	function isEmailConfirmationPending() {
 		global $wgEmailAuthentication;
@@ -2743,20 +2983,40 @@ class User {
 	}
 
 	/**
-	 * Get the timestamp of account creation, or false for
-	 * non-existent/anonymous user accounts
+	 * Get the timestamp of account creation.
 	 *
-	 * @return mixed
+	 * @return \types{\string,\bool} string Timestamp of account creation, or false for
+	 *                                non-existent/anonymous user accounts.
 	 */
 	public function getRegistration() {
-		return $this->mId > 0
+		return $this->getId() > 0
 			? $this->mRegistration
 			: false;
 	}
+	
+	/**
+	 * Get the timestamp of the first edit
+	 *
+	 * @return \types{\string,\bool} string Timestamp of first edit, or false for
+	 *                                non-existent/anonymous user accounts.
+	 */
+	public function getFirstEditTimestamp() {
+		if( $this->getId() == 0 ) return false; // anons
+		$dbr = wfGetDB( DB_SLAVE );
+		$time = $dbr->selectField( 'revision', 'rev_timestamp',
+			array( 'rev_user' => $this->getId() ),
+			__METHOD__,
+			array( 'ORDER BY' => 'rev_timestamp ASC' )
+		);
+		if( !$time ) return false; // no edits
+		return wfTimestamp( TS_MW, $time );
+	}	
 
 	/**
-	 * @param $groups Array: list of groups
-	 * @return array list of permission key names for given groups combined
+	 * Get the permissions associated with a given list of groups
+	 *
+	 * @param $groups \type{\arrayof{\string}} List of internal group names
+	 * @return \type{\arrayof{\string}} List of permission key names for given groups combined
 	 */
 	static function getGroupPermissions( $groups ) {
 		global $wgGroupPermissions;
@@ -2764,15 +3024,35 @@ class User {
 		foreach( $groups as $group ) {
 			if( isset( $wgGroupPermissions[$group] ) ) {
 				$rights = array_merge( $rights,
+					// array_filter removes empty items
 					array_keys( array_filter( $wgGroupPermissions[$group] ) ) );
 			}
 		}
-		return $rights;
+		return array_unique($rights);
+	}
+	
+	/**
+	 * Get all the groups who have a given permission
+	 * 
+	 * @param $role \string Role to check
+	 * @return \type{\arrayof{\string}} List of internal group names with the given permission
+	 */
+	static function getGroupsWithPermission( $role ) {
+		global $wgGroupPermissions;
+		$allowedGroups = array();
+		foreach ( $wgGroupPermissions as $group => $rights ) {
+			if ( isset( $rights[$role] ) && $rights[$role] ) {
+				$allowedGroups[] = $group;
+			}
+		}
+		return $allowedGroups;
 	}
 
 	/**
-	 * @param $group String: key name
-	 * @return string localized descriptive name for group, if provided
+	 * Get the localized descriptive name for a group, if it exists
+	 *
+	 * @param $group \string Internal group name
+	 * @return \string Localized descriptive group name
 	 */
 	static function getGroupName( $group ) {
 		global $wgMessageCache;
@@ -2785,8 +3065,10 @@ class User {
 	}
 
 	/**
-	 * @param $group String: key name
-	 * @return string localized descriptive name for member of a group, if provided
+	 * Get the localized descriptive name for a member of a group, if it exists
+	 *
+	 * @param $group \string Internal group name
+	 * @return \string Localized name for group member
 	 */
 	static function getGroupMember( $group ) {
 		global $wgMessageCache;
@@ -2801,9 +3083,8 @@ class User {
 	/**
 	 * Return the set of defined explicit groups.
 	 * The implicit groups (by default *, 'user' and 'autoconfirmed')
-	 * are not included, as they are defined automatically,
-	 * not in the database.
-	 * @return array
+	 * are not included, as they are defined automatically, not in the database.
+	 * @return \type{\arrayof{\string}} Array of internal group names
 	 */
 	static function getAllGroups() {
 		global $wgGroupPermissions;
@@ -2814,7 +3095,8 @@ class User {
 	}
 
 	/**
-	 * Get a list of all available permissions
+	 * Get a list of all available permissions.
+	 * @return \type{\arrayof{\string}} Array of permission names
 	 */
 	static function getAllRights() {
 		if ( self::$mAllRights === false ) {
@@ -2831,8 +3113,7 @@ class User {
 
 	/**
 	 * Get a list of implicit groups
-	 *
-	 * @return array
+	 * @return \type{\arrayof{\string}} Array of internal group names
 	 */
 	public static function getImplicitGroups() {
 		global $wgImplicitGroups;
@@ -2844,8 +3125,8 @@ class User {
 	/**
 	 * Get the title of a page describing a particular group
 	 *
-	 * @param $group Name of the group
-	 * @return mixed
+	 * @param $group \string Internal group name
+	 * @return \types{\type{Title},\bool} Title of the page if it exists, false otherwise
 	 */
 	static function getGroupPage( $group ) {
 		global $wgMessageCache;
@@ -2860,11 +3141,12 @@ class User {
 	}
 
 	/**
-	 * Create a link to the group in HTML, if available
+	 * Create a link to the group in HTML, if available; 
+	 * else return the group name.
 	 *
-	 * @param $group Name of the group
-	 * @param $text The text of the link
-	 * @return mixed
+	 * @param $group \string Internal name of the group
+	 * @param $text \string The text of the link
+	 * @return \string HTML link to the group
 	 */
 	static function makeGroupLinkHTML( $group, $text = '' ) {
 		if( $text == '' ) {
@@ -2881,11 +3163,12 @@ class User {
 	}
 
 	/**
-	 * Create a link to the group in Wikitext, if available
+	 * Create a link to the group in Wikitext, if available; 
+	 * else return the group name.
 	 *
-	 * @param $group Name of the group
-	 * @param $text The text of the link (by default, the name of the group)
-	 * @return mixed
+	 * @param $group \string Internal name of the group
+	 * @param $text \string The text of the link
+	 * @return \string Wikilink to the group
 	 */
 	static function makeGroupLinkWiki( $group, $text = '' ) {
 		if( $text == '' ) {
@@ -2944,6 +3227,12 @@ class User {
 		$this->invalidateCache();
 	}
 	
+	/**
+	 * Get the description of a given right
+	 *
+	 * @param $right \string Right to query
+	 * @return \string Localized description of the right
+	 */
 	static function getRightDescription( $right ) {
 		global $wgMessageCache;
 		$wgMessageCache->loadAllMessages();
@@ -2957,8 +3246,9 @@ class User {
 	/**
 	 * Make an old-style password hash
 	 *
-	 * @param $password String: plain-text password
-	 * @param $userId String: user ID
+	 * @param $password \string Plain-text password
+	 * @param $userId \string User ID
+	 * @return \string Password hash
 	 */
 	static function oldCrypt( $password, $userId ) {
 		global $wgPasswordSalt;
@@ -2972,19 +3262,26 @@ class User {
 	/**
 	 * Make a new-style password hash
 	 *
-	 * @param $password String: plain-text password
-	 * @param $salt String: salt, may be random or the user ID. False to generate a salt.
+	 * @param $password \string Plain-text password
+	 * @param $salt \string Optional salt, may be random or the user ID. 
+	 *                     If unspecified or false, will generate one automatically
+	 * @return \string Password hash
 	 */
 	static function crypt( $password, $salt = false ) {
 		global $wgPasswordSalt;
 
-		if($wgPasswordSalt) {
+		$hash = '';
+		if( !wfRunHooks( 'UserCryptPassword', array( &$password, &$salt, &$wgPasswordSalt, &$hash ) ) ) {
+			return $hash;
+		}
+		
+		if( $wgPasswordSalt ) {
 			if ( $salt === false ) {
 				$salt = substr( wfGenerateToken(), 0, 8 );
 			}
 			return ':B:' . $salt . ':' . md5( $salt . '-' . md5( $password ) );
 		} else {
-			return ':A:' . md5( $password);
+			return ':A:' . md5( $password );
 		}
 	}
 
@@ -2992,13 +3289,20 @@ class User {
 	 * Compare a password hash with a plain-text password. Requires the user
 	 * ID if there's a chance that the hash is an old-style hash.
 	 *
-	 * @param $hash String: password hash
-	 * @param $password String: plain-text password to compare
-	 * @param $userId String: user ID for old-style password salt
+	 * @param $hash \string Password hash
+	 * @param $password \string Plain-text password to compare
+	 * @param $userId \string User ID for old-style password salt
+	 * @return \bool
 	 */
 	static function comparePasswords( $hash, $password, $userId = false ) {
 		$m = false;
 		$type = substr( $hash, 0, 3 );
+		
+		$result = false;
+		if( !wfRunHooks( 'UserComparePasswords', array( &$hash, &$password, &$userId, &$result ) ) ) {
+			return $result;
+		}
+		
 		if ( $type == ':A:' ) {
 			# Unsalted
 			return md5( $password ) === substr( $hash, 3 );
@@ -3011,4 +3315,41 @@ class User {
 			return self::oldCrypt( $password, $userId ) === $hash;
 		}
 	}
+	
+	/**
+	 * Add a newuser log entry for this user
+	 * @param $byEmail Boolean: account made by email?
+	 */
+	public function addNewUserLogEntry( $byEmail = false ) {
+		global $wgUser, $wgContLang, $wgNewUserLog;
+		if( empty($wgNewUserLog) ) {
+			return true; // disabled
+		}
+		$talk = $wgContLang->getFormattedNsText( NS_TALK );
+		if( $this->getName() == $wgUser->getName() ) {
+			$action = 'create';
+			$message = '';
+		} else {
+			$action = 'create2';
+			$message = $byEmail ? wfMsgForContent( 'newuserlog-byemail' ) : '';
+		}
+		$log = new LogPage( 'newusers' );
+		$log->addEntry( $action, $this->getUserPage(), $message, array( $this->getId() ) );
+		return true;
+	}
+
+	/**
+	 * Add an autocreate newuser log entry for this user
+	 * Used by things like CentralAuth and perhaps other authplugins.
+	 */
+	public function addNewUserLogEntryAutoCreate() {
+		global $wgNewUserLog;
+		if( empty($wgNewUserLog) ) {
+			return true; // disabled
+		}
+		$log = new LogPage( 'newusers', false );
+		$log->addEntry( 'autocreate', $this->getUserPage(), '', array( $this->getId() ) );
+		return true;
+	}
+
 }