From: Alexandre Emsenhuber Date: Tue, 12 Jan 2010 21:49:47 +0000 (+0000) Subject: document a bit X-Git-Tag: 1.31.0-rc.0~38301 X-Git-Url: https://git.cyclocoop.org/%242?a=commitdiff_plain;h=5fc268d803740f0da842c9848e100ae8fcb94816;p=lhc%2Fweb%2Fwiklou.git document a bit --- diff --git a/includes/UserRightsProxy.php b/includes/UserRightsProxy.php index 7f3af08d13..0d6b815117 100644 --- a/includes/UserRightsProxy.php +++ b/includes/UserRightsProxy.php @@ -1,31 +1,55 @@ db = $db; $this->database = $database; $this->name = $name; $this->id = intval( $id ); } - + + /** + * Accessor for $this->database + * + * @return String: database name + */ public function getDBName() { return $this->database; } /** * Confirm the selected database name is a valid local interwiki database name. - * @return bool + * + * @param $database String: database name + * @return Boolean */ public static function validDatabase( $database ) { global $wgLocalDatabases; return in_array( $database, $wgLocalDatabases ); } + /** + * Same as User::whoIs() + * + * @param $database String: database name + * @param $id Integer: user ID + * @return String: user name or false if the user doesn't exist + */ public static function whoIs( $database, $id ) { $user = self::newFromId( $database, $id ); if( $user ) { @@ -37,12 +61,22 @@ class UserRightsProxy { /** * Factory function; get a remote user entry by ID number. + * + * @param $database String: database name + * @param $id Integer: user ID * @return UserRightsProxy or null if doesn't exist */ public static function newFromId( $database, $id ) { return self::newFromLookup( $database, 'user_id', intval( $id ) ); } + /** + * Factory function; get a remote user entry by name. + * + * @param $database String: database name + * @param $name String: user name + * @return UserRightsProxy or null if doesn't exist + */ public static function newFromName( $database, $name ) { return self::newFromLookup( $database, 'user_name', $name ); } @@ -66,8 +100,9 @@ class UserRightsProxy { /** * Open a database connection to work on for the requested user. * This may be a new connection to another database for remote users. - * @param $database string - * @return Database or null if invalid selection + * + * @param $database String + * @return DatabaseBase or null if invalid selection */ public static function getDB( $database ) { global $wgLocalDatabases, $wgDBname; @@ -90,15 +125,27 @@ class UserRightsProxy { return $this->getId() == 0; } + /** + * Same as User::getName() + * + * @return String + */ public function getName() { return $this->name . '@' . $this->database; } + /** + * Same as User::getUserPage() + * + * @return Title object + */ public function getUserPage() { return Title::makeTitle( NS_USER, $this->getName() ); } - // Replaces getUserGroups() + /** + * Replaces User::getUserGroups() + */ function getGroups() { $res = $this->db->select( 'user_groups', array( 'ug_group' ), @@ -111,7 +158,9 @@ class UserRightsProxy { return $groups; } - // replaces addUserGroup + /** + * Replaces User::addUserGroup() + */ function addGroup( $group ) { $this->db->insert( 'user_groups', array( @@ -122,7 +171,9 @@ class UserRightsProxy { array( 'IGNORE' ) ); } - // replaces removeUserGroup + /** + * Replaces User::removeUserGroup() + */ function removeGroup( $group ) { $this->db->delete( 'user_groups', array( @@ -132,7 +183,9 @@ class UserRightsProxy { __METHOD__ ); } - // replaces touchUser + /** + * Replaces User::touchUser() + */ function invalidateCache() { $this->db->update( 'user', array( 'user_touched' => $this->db->timestamp() ), diff --git a/includes/WikiMap.php b/includes/WikiMap.php index 307916e184..e68a232f8e 100644 --- a/includes/WikiMap.php +++ b/includes/WikiMap.php @@ -3,11 +3,17 @@ /** * Helper tools for dealing with other locally-hosted wikis */ - class WikiMap { - static function getWiki( $wikiID ) { + + /** + * Get a WikiReference object for $wikiID + * + * @param $wikiID String: wiki'd id (generally database name) + * @return WikiReference object or null if the wiki was not found + */ + public static function getWiki( $wikiID ) { global $wgConf, $IP; - + $wgConf->loadFullData(); list( $major, $minor ) = $wgConf->siteFromDB( $wikiID ); @@ -22,59 +28,90 @@ class WikiMap { } } - // Convenience functions from GlobalBlocking - static function getWikiName( $wiki_id ) { - // We can give more info than just the wiki id! - $wiki = WikiMap::getWiki( $wiki_id ); - - if ($wiki) { + /** + * Convenience to get the wiki's display name + * + * @todo We can give more info than just the wiki id! + * @param $wikiID String: wiki'd id (generally database name) + * @return Wiki's name or $wiki_id if the wiki was not found + */ + public static function getWikiName( $wikiID ) { + $wiki = WikiMap::getWiki( $wikiID ); + + if ( $wiki ) { return $wiki->getDisplayName(); } return $wiki_id; } - - static function foreignUserLink( $wiki_id, $user, $text=null ) { - return self::makeForeignLink( $wiki_id, "User:$user", $text ); + + /** + * Convenience to get a link to a user page on a foreign wiki + * + * @param $wikiID String: wiki'd id (generally database name) + * @param $user String: user name (must be normalised before calling this function!) + * @param $text String: link's text; optional, default to "User:$user" + * @return String: HTML link or false if the wiki was not found + */ + public static function foreignUserLink( $wikiID, $user, $text=null ) { + return self::makeForeignLink( $wikiID, "User:$user", $text ); } - - static function makeForeignLink( $wiki_id, $page, $text=null ) { + + /** + * Convenience to get a link to a page on a foreign wiki + * + * @param $wikiID String: wiki'd id (generally database name) + * @param $page String: page name (must be normalised before calling this function!) + * @param $text String: link's text; optional, default to $page + * @return String: HTML link or false if the wiki was not found + */ + public static function makeForeignLink( $wikiID, $page, $text=null ) { global $wgUser; $sk = $wgUser->getSkin(); if ( !$text ) - $text=$page; + $text = $page; - $url = self::getForeignURL( $wiki_id, $page ); + $url = self::getForeignURL( $wikiID, $page ); if ( $url === false ) return false; return $sk->makeExternalLink( $url, $text ); } - - static function getForeignURL( $wiki_id, $page ) { - $wiki = WikiMap::getWiki( $wiki_id ); + + /** + * Convenience to get a url to a page on a foreign wiki + * + * @param $wikiID String: wiki'd id (generally database name) + * @param $page String: page name (must be normalised before calling this function!) + * @return String: URL or false if the wiki was not found + */ + public static function getForeignURL( $wikiID, $page ) { + $wiki = WikiMap::getWiki( $wikiID ); - if ($wiki) + if ( $wiki ) return $wiki->getUrl( $page ); return false; } } +/** + * Reference to a locally-hosted wiki + */ class WikiReference { private $mMinor; ///< 'en', 'meta', 'mediawiki', etc private $mMajor; ///< 'wiki', 'wiktionary', etc private $mServer; ///< server override, 'www.mediawiki.org' private $mPath; ///< path override, '/wiki/$1' - function __construct( $major, $minor, $server, $path ) { + public function __construct( $major, $minor, $server, $path ) { $this->mMajor = $major; $this->mMinor = $minor; $this->mServer = $server; $this->mPath = $path; } - function getHostname() { + public function getHostname() { $prefixes = array( 'http://', 'https://' ); foreach ( $prefixes as $prefix ) { if ( substr( $this->mServer, 0, strlen( $prefix ) ) ) { @@ -85,9 +122,12 @@ class WikiReference { } /** - * pretty it up + * Get the the URL in a way to de displayed to the user + * More or less Wikimedia specific + * + * @return String */ - function getDisplayName() { + public function getDisplayName() { $url = $this->getUrl( '' ); $url = preg_replace( '!^https?://!', '', $url ); $url = preg_replace( '!/index\.php(\?title=|/)$!', '/', $url ); @@ -96,14 +136,26 @@ class WikiReference { return $url; } + /** + * Helper function for getUrl() + * + * @todo FIXME: this may be generalized... + * @param $page String: page name (must be normalised before calling this function!) + * @return String: Url fragment + */ private function getLocalUrl( $page ) { - // FIXME: this may be generalized... return str_replace( '$1', wfUrlEncode( str_replace( ' ', '_', $page ) ), $this->mPath ); } - function getUrl( $page ) { + /** + * Get a URL to a page on this foreign wiki + * + * @param $page String: page name (must be normalised before calling this function!) + * @return String: Url + */ + public function getUrl( $page ) { return - $this->mServer . + $this->mServer . $this->getLocalUrl( $page ); } }