update to MediaWiki 1.16.0

1 files changed, 304 insertions, 0 deletions

diff --git a/includes/ExternalUser.php b/includes/ExternalUser.php
new file mode 100644
index 00000000..65dae617
--- /dev/null
+++ b/includes/ExternalUser.php
@@ -0,0 +1,304 @@
+<?php
+
+# Copyright (C) 2009 Aryeh Gregor
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+# http://www.gnu.org/copyleft/gpl.html
+
+/**
+ * @defgroup ExternalUser ExternalUser
+ */
+
+/**
+ * A class intended to supplement, and perhaps eventually replace, AuthPlugin.
+ * See: http://www.mediawiki.org/wiki/ExternalAuth
+ *
+ * The class represents a user whose data is in a foreign database.  The
+ * database may have entirely different conventions from MediaWiki, but it's
+ * assumed to at least support the concept of a user id (possibly not an
+ * integer), a user name (possibly not meeting MediaWiki's username
+ * requirements), and a password.
+ *
+ * @ingroup ExternalUser
+ */
+abstract class ExternalUser {
+	protected function __construct() {}
+
+	/**
+	 * Wrappers around initFrom*().
+	 */
+
+	/**
+	 * @param $name string
+	 * @return mixed ExternalUser, or false on failure
+	 */
+	public static function newFromName( $name ) {
+		global $wgExternalAuthType;
+		if ( is_null( $wgExternalAuthType ) ) {
+			return false;
+		}
+		$obj = new $wgExternalAuthType;
+		if ( !$obj->initFromName( $name ) ) {
+			return false;
+		}
+		return $obj;
+	}
+
+	/**
+	 * @param $id string
+	 * @return mixed ExternalUser, or false on failure
+	 */
+	public static function newFromId( $id ) {
+		global $wgExternalAuthType;
+		if ( is_null( $wgExternalAuthType ) ) {
+			return false;
+		}
+		$obj = new $wgExternalAuthType;
+		if ( !$obj->initFromId( $id ) ) {
+			return false;
+		}
+		return $obj;
+	}
+
+	/**
+	 * @return mixed ExternalUser, or false on failure
+	 */
+	public static function newFromCookie() {
+		global $wgExternalAuthType;
+		if ( is_null( $wgExternalAuthType ) ) {
+			return false;
+		}
+		$obj = new $wgExternalAuthType;
+		if ( !$obj->initFromCookie() ) {
+			return false;
+		}
+		return $obj;
+	}
+
+	/**
+	 * Creates the object corresponding to the given User object, assuming the
+	 * user exists on the wiki and is linked to an external account.  If either
+	 * of these is false, this will return false.
+	 *
+	 * This is a wrapper around newFromId().
+	 *
+	 * @param $user User
+	 * @return mixed ExternalUser or false
+	 */
+	public static function newFromUser( $user ) {
+		global $wgExternalAuthType;
+		if ( is_null( $wgExternalAuthType ) ) {
+			# Short-circuit to avoid database query in common case so no one
+			# kills me
+			return false;
+		}
+
+		$dbr = wfGetDB( DB_SLAVE );
+		$id = $dbr->selectField( 'external_user', 'eu_external_id',
+			array( 'eu_local_id' => $user->getId() ), __METHOD__ );
+		if ( $id === false ) {
+			return false;
+		}
+		return self::newFromId( $id );
+	}
+
+	/**
+	 * Given a name, which is a string exactly as input by the user in the
+	 * login form but with whitespace stripped, initialize this object to be
+	 * the corresponding ExternalUser.  Return true if successful, otherwise
+	 * false.
+	 *
+	 * @param $name string
+	 * @return bool Success?
+	 */
+	protected abstract function initFromName( $name );
+
+	/**
+	 * Given an id, which was at some previous point in history returned by
+	 * getId(), initialize this object to be the corresponding ExternalUser.
+	 * Return true if successful, false otherwise.
+	 *
+	 * @param $id string
+	 * @return bool Success?
+	 */
+	protected abstract function initFromId( $id );
+
+	/**
+	 * Try to magically initialize the user from cookies or similar information
+	 * so he or she can be logged in on just viewing the wiki.  If this is
+	 * impossible to do, just return false.
+	 *
+	 * TODO: Actually use this.
+	 *
+	 * @return bool Success?
+	 */
+	protected function initFromCookie() {
+		return false;
+	}
+
+	/**
+	 * This must return some identifier that stably, uniquely identifies the
+	 * user.  In a typical web application, this could be an integer
+	 * representing the "user id".  In other cases, it might be a string.  In
+	 * any event, the return value should be a string between 1 and 255
+	 * characters in length; must uniquely identify the user in the foreign
+	 * database; and, if at all possible, should be permanent.
+	 *
+	 * This will only ever be used to reconstruct this ExternalUser object via
+	 * newFromId().  The resulting object in that case should correspond to the
+	 * same user, even if details have changed in the interim (e.g., renames or
+	 * preference changes).
+	 *
+	 * @return string
+	 */
+	abstract public function getId();
+
+	/**
+	 * This must return the name that the user would normally use for login to
+	 * the external database.  It is subject to no particular restrictions
+	 * beyond rudimentary sanity, and in particular may be invalid as a
+	 * MediaWiki username.  It's used to auto-generate an account name that
+	 * *is* valid for MediaWiki, either with or without user input, but
+	 * basically is only a hint.
+	 *
+	 * @return string
+	 */
+	abstract public function getName();
+
+	/**
+	 * Is the given password valid for the external user?  The password is
+	 * provided in plaintext.
+	 *
+	 * @param $password string
+	 * @return bool
+	 */
+	abstract public function authenticate( $password );
+
+	/**
+	 * Retrieve the value corresponding to the given preference key.  The most
+	 * important values are:
+	 *
+	 * - emailaddress
+	 * - language
+	 *
+	 * The value must meet MediaWiki's requirements for values of this type,
+	 * and will be checked for validity before use.  If the preference makes no
+	 * sense for the backend, or it makes sense but is unset for this user, or
+	 * is unrecognized, return null.
+	 *
+	 * $pref will never equal 'password', since passwords are usually hashed
+	 * and cannot be directly retrieved.  authenticate() is used for this
+	 * instead.
+	 *
+	 * TODO: Currently this is only called for 'emailaddress'; generalize!  Add
+	 * some config option to decide which values are grabbed on user
+	 * initialization.
+	 *
+	 * @param $pref string
+	 * @return mixed
+	 */
+	public function getPref( $pref ) {
+		return null;
+	}
+
+	/**
+	 * Return an array of identifiers for all the foreign groups that this user
+	 * has.  The identifiers are opaque objects that only need to be
+	 * specifiable by the administrator in LocalSettings.php when configuring
+	 * $wgAutopromote.  They may be, for instance, strings or integers.
+	 *
+	 * TODO: Support this in $wgAutopromote.
+	 *
+	 * @return array
+	 */
+	public function getGroups() {
+		return array();
+	}
+
+	/**
+	 * Given a preference key (e.g., 'emailaddress'), provide an HTML message
+	 * telling the user how to change it in the external database.  The
+	 * administrator has specified that this preference cannot be changed on
+	 * the wiki, and may only be changed in the foreign database.  If no
+	 * message is available, such as for an unrecognized preference, return
+	 * false.
+	 *
+	 * TODO: Use this somewhere.
+	 *
+	 * @param $pref string
+	 * @return mixed String or false
+	 */
+	public static function getPrefMessage( $pref ) {
+		return false;
+	}
+
+	/**
+	 * Set the given preference key to the given value.  Two important
+	 * preference keys that you might want to implement are 'password' and
+	 * 'emailaddress'.  If the set fails, such as because the preference is
+	 * unrecognized or because the external database can't be changed right
+	 * now, return false.  If it succeeds, return true.
+	 *
+	 * If applicable, you should make sure to validate the new value against
+	 * any constraints the external database may have, since MediaWiki may have
+	 * more limited constraints (e.g., on password strength).
+	 *
+	 * TODO: Untested.
+	 *
+	 * @param $key string
+	 * @param $value string
+	 * @return bool Success?
+	 */
+	public static function setPref( $key, $value ) {
+		return false;
+	}
+
+	/**
+	 * Create a link for future reference between this object and the provided
+	 * user_id.  If the user was already linked, the old link will be
+	 * overwritten.
+	 *
+	 * This is part of the core code and is not overridable by specific
+	 * plugins.  It's in this class only for convenience.
+	 *
+	 * @param $id int user_id
+	 */
+	public final function linkToLocal( $id ) {
+		$dbw = wfGetDB( DB_MASTER );
+		$dbw->replace( 'external_user',
+			array( 'eu_local_id', 'eu_external_id' ),
+			array( 'eu_local_id' => $id,
+				   'eu_external_id' => $this->getId() ),
+			__METHOD__ );
+	}
+	
+	/**
+	 * Check whether this external user id is already linked with
+	 * a local user.
+	 * @return Mixed User if the account is linked, Null otherwise.
+	 */
+	public final function getLocalUser(){
+		$dbr = wfGetDb( DB_SLAVE );
+		$row = $dbr->selectRow(
+			'external_user',
+			'*',
+			array( 'eu_external_id' => $this->getId() )
+		);
+		return $row
+			? User::newFromId( $row->eu_local_id )
+			: null;
+	}
+	
+}