From 8f416baead93a48e5799e44b8bd2e2c4859f4e04 Mon Sep 17 00:00:00 2001 From: Pierre Schmitz Date: Fri, 14 Sep 2007 13:18:58 +0200 Subject: auf Version 1.11 aktualisiert; Login-Bug behoben --- docs/README | 6 +- docs/design.txt | 25 ++-- docs/hooks.txt | 332 ++++++++++++++++++++++++++++++++++++++--------------- docs/memcached.txt | 2 +- docs/schema.txt | 3 + docs/title.txt | 9 +- 6 files changed, 262 insertions(+), 115 deletions(-) (limited to 'docs') diff --git a/docs/README b/docs/README index 43ac8ef5..1ec3986b 100644 --- a/docs/README +++ b/docs/README @@ -1,9 +1,9 @@ -[July 5th 2005] +[May 31st 2007] The 'docs' directory contain various text files that should help you understand the most importants classes in MediaWiki. -API documentation is sometime generated and uploaded at: +API documentation is automatically generated and updated daily at: http://svn.wikimedia.org/doc/ You can get a fresh version using 'make doc' or mwdocgen.php @@ -13,5 +13,5 @@ in the ../maintenance/ directory. For end user / administrators, most of the documentation is located online at: - http://meta.wikimedia.org/wiki/Help:Help + http://www.mediawiki.org/wiki/Project:Help diff --git a/docs/design.txt b/docs/design.txt index 8f24d0d8..1a35d5b0 100644 --- a/docs/design.txt +++ b/docs/design.txt @@ -34,8 +34,7 @@ Primary source files/objects: calling output() to send it all. It could be easily changed to send incrementally if that becomes useful, but I prefer the flexibility. This should also do the output encoding. - The system allocates a global one in $wgOut. This class - also handles converting wikitext format to HTML. + The system allocates a global one in $wgOut. Title Represents the title of an article, and does all the work @@ -69,7 +68,9 @@ Primary source files/objects: Language Represents the language used for incidental text, and also has some character encoding functions and other locale stuff. - A global one is allocated in $wgLang. + The current user interface language is instantiated as $wgLang, + and the local content language as $wgContLang; be sure to use + the *correct* language object depending upon the circumstances. LinkCache Keeps information on existence of articles. See LINKCACHE.TXT. @@ -94,13 +95,14 @@ Naming/coding conventions: its own line or the statement that opened the block--that's confusing as hell. - - PHP doesn't have "private" member variables of functions, - so I've used the comment "/* private */" in some places to - indicate my intent. Don't access things marked that way - from outside the class def--use the accessor functions (or - make your own if you need them). Yes, even some globals - are marked private, because PHP is broken and doesn't - allow static class variables. + - Certain functions and class members are marked with + /* private */, rather than being marked as such. This is a + hold-over from PHP 4, which didn't support proper visibilities. + You should not access things marked in this manner outside the + class/inheritance line as this code is subjected to be updated + in a manner that enforces this at some time in the near future, + and things will break. New code should use the standard method of + setting visibilities as normal. - Member variables are generally "mXxx" to distinguish them. This should make it easier to spot errors of forgetting the @@ -123,5 +125,4 @@ Naming/coding conventions: Other conventions: Top-level functions are wfFuncname(), names of session variables are wsName, cookies wcName, and form field - values wpName ("p" for "POST"). - + values wpName ("p" for "POST"). \ No newline at end of file diff --git a/docs/hooks.txt b/docs/hooks.txt index 9f5d289f..9614bead 100644 --- a/docs/hooks.txt +++ b/docs/hooks.txt @@ -35,20 +35,20 @@ order of a title before displaying the article; the other converts the title to all uppercase letters. Currently, in MediaWiki code, we would handle this as follows (note: not real code, here): - function showAnArticle($article) { - global $wgReverseTitle, $wgCapitalizeTitle; - - if ($wgReverseTitle) { - wfReverseTitle($article); - } - - if ($wgCapitalizeTitle) { - wfCapitalizeTitle($article); - } - - # code to actually show the article goes here - } - + function showAnArticle($article) { + global $wgReverseTitle, $wgCapitalizeTitle; + + if ($wgReverseTitle) { + wfReverseTitle($article); + } + + if ($wgCapitalizeTitle) { + wfCapitalizeTitle($article); + } + + # code to actually show the article goes here + } + An extension writer, or a local admin, will often add custom code to the function -- with or without a global variable. For example, someone wanting email notification when an article is shown may add: @@ -75,15 +75,15 @@ Using a hook-running strategy, we can avoid having all this option-specific stuff in our mainline code. Using hooks, the function becomes: - function showAnArticle($article) { + function showAnArticle($article) { - if (wfRunHooks('ArticleShow', array(&$article))) { - - # code to actually show the article goes here - - wfRunHooks('ArticleShowComplete', array(&$article)); + if (wfRunHooks('ArticleShow', array(&$article))) { + + # code to actually show the article goes here + + wfRunHooks('ArticleShowComplete', array(&$article)); + } } - } We've cleaned up the code here by removing clumps of weird, infrequently used code and moving them off somewhere else. It's much @@ -96,24 +96,24 @@ having little title-reversing if-blocks spread all over the codebase in showAnArticle, deleteAnArticle, exportArticle, etc., we can concentrate it all in an extension file: - function reverseArticleTitle($article) { - # ... - } + function reverseArticleTitle($article) { + # ... + } - function reverseForExport($article) { - # ... - } + function reverseForExport($article) { + # ... + } The setup function for the extension just has to add its hook functions to the appropriate events: - setupTitleReversingExtension() { - global $wgHooks; - - $wgHooks['ArticleShow'][] = 'reverseArticleTitle'; - $wgHooks['ArticleDelete'][] = 'reverseArticleTitle'; - $wgHooks['ArticleExport'][] = 'reverseForExport'; - } + setupTitleReversingExtension() { + global $wgHooks; + + $wgHooks['ArticleShow'][] = 'reverseArticleTitle'; + $wgHooks['ArticleDelete'][] = 'reverseArticleTitle'; + $wgHooks['ArticleExport'][] = 'reverseForExport'; + } Having all this code related to the title-reversion option in one place means that it's easier to read and understand; you don't have to @@ -124,8 +124,8 @@ used -- making for some slight savings in memory and load-up performance at runtime. Admins who want to have all the reversed titles can add: - require_once('extensions/ReverseTitle.php'); - + require_once('extensions/ReverseTitle.php'); + ...to their LocalSettings.php file; those of us who don't want or need it can just leave it out. @@ -143,31 +143,31 @@ A hook is a chunk of code run at some particular event. It consists of: Hooks are registered by adding them to the global $wgHooks array for a given event. All the following are valid ways to define hooks: - $wgHooks['EventName'][] = 'someFunction'; # function, no data - $wgHooks['EventName'][] = array('someFunction', $someData); - $wgHooks['EventName'][] = array('someFunction'); # weird, but OK - - $wgHooks['EventName'][] = $object; # object only - $wgHooks['EventName'][] = array($object, 'someMethod'); - $wgHooks['EventName'][] = array($object, 'someMethod', $someData); - $wgHooks['EventName'][] = array($object); # weird but OK + $wgHooks['EventName'][] = 'someFunction'; # function, no data + $wgHooks['EventName'][] = array('someFunction', $someData); + $wgHooks['EventName'][] = array('someFunction'); # weird, but OK + + $wgHooks['EventName'][] = $object; # object only + $wgHooks['EventName'][] = array($object, 'someMethod'); + $wgHooks['EventName'][] = array($object, 'someMethod', $someData); + $wgHooks['EventName'][] = array($object); # weird but OK When an event occurs, the function (or object method) will be called with the optional data provided as well as event-specific parameters. The above examples would result in the following code being executed when 'EventName' happened: - # function, no data - someFunction($param1, $param2) - # function with data - someFunction($someData, $param1, $param2) - - # object only - $object->onEventName($param1, $param2) - # object with method - $object->someMethod($param1, $param2) - # object with method and data - $object->someMethod($someData, $param1, $param2) + # function, no data + someFunction($param1, $param2) + # function with data + someFunction($someData, $param1, $param2) + + # object only + $object->onEventName($param1, $param2) + # object with method + $object->someMethod($param1, $param2) + # object with method and data + $object->someMethod($someData, $param1, $param2) Note that when an object is the hook, and there's no specified method, the default method called is 'onEventName'. For different events this @@ -176,8 +176,8 @@ would be different: 'onArticleSave', 'onUserLogin', etc. The extra data is useful if we want to use the same function or object for different purposes. For example: - $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling'); - $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion'); + $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'TimStarling'); + $wgHooks['ArticleSaveComplete'][] = array('ircNotify', 'brion'); This code would result in ircNotify being run twice when an article is saved: once for 'TimStarling', and once for 'brion'. @@ -195,12 +195,12 @@ the main functionality. For example, if you wanted to authenticate users to a custom system (LDAP, another PHP program, whatever), you could do: - $wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer); - - function ldapLogin($username, $password) { - # log user into LDAP - return false; - } + $wgHooks['UserLogin'][] = array('ldapLogin', $ldapServer); + + function ldapLogin($username, $password) { + # log user into LDAP + return false; + } Returning false makes less sense for events where the action is complete, and will normally be ignored. @@ -210,14 +210,15 @@ complete, and will normally be ignored. A calling function or method uses the wfRunHooks() function to run the hooks related to a particular event, like so: - class Article { - # ... - function protect() { - global $wgUser; - if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) { - # protect the article - wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser)); - } + class Article { + # ... + function protect() { + global $wgUser; + if (wfRunHooks('ArticleProtect', array(&$this, &$wgUser))) { + # protect the article + wfRunHooks('ArticleProtectComplete', array(&$this, &$wgUser)); + } + } } wfRunHooks() returns true if the calling function should continue @@ -237,6 +238,13 @@ protocol came about after MediaWiki 1.4rc1. This is a list of known events and parameters; please add to it if you're going to add events to the MediaWiki code. +'AbortLogin': Return false to cancel account login. +$user: the User object being authenticated against +$password: the password being submitted, not yet checked for validity +&$retval: a LoginForm class constant to return from authenticateUserData(); + default is LoginForm::ABORTED. Note that the client may be using + a machine API rather than the HTML user interface. + 'AbortNewAccount': Return false to cancel account creation. $user: the User object about to be created (read-only, incomplete) $message: out parameter: error message to display on abort @@ -244,6 +252,15 @@ $message: out parameter: error message to display on abort 'AddNewAccount': after a user account is created $user: the User object that was created. (Parameter added in 1.7) +'AjaxAddScript': Called in output page just before the initialisation +of the javascript ajax engine. The hook is only called when ajax +is enabled ( $wgUseAjax = true; ). + +'AlternateEdit': before checking if an user can edit a page and +before showing the edit form ( EditPage::edit() ). This is triggered +on &action=edit. +$EditPage : the EditPage object + 'ArticleDelete': before an article is deleted $article: the article (object) being deleted $user: the user (object) deleting the article @@ -254,6 +271,17 @@ $article: the article that was deleted $user: the user that deleted the article $reason: the reason the article was deleted +'ArticleInsertComplete': After an article is created +$article: Article created +$user: User creating the article +$text: New content +$summary: Edit summary/comment +$isMinor: Whether or not the edit was marked as minor +$isWatch: (No longer used) +$section: (No longer used) +$flags: Flags passed to Article::doEdit() +$revision: New Revision of the article + 'ArticleProtect': before an article is protected $article: the article being protected $user: the user doing the protection @@ -277,6 +305,17 @@ $isminor: minor flag $iswatch: watch flag $section: section # +'ArticleSaveComplete': After an article has been updated +$article: Article modified +$user: User performing the modification +$text: New content +$summary: Edit summary/comment +$isMinor: Whether or not the edit was marked as minor +$isWatch: (No longer used) +$section: (No longer used) +$flags: Flags passed to Article::doEdit() +$revision: New Revision of the article + 'ArticleSaveComplete': after an article is saved $article: the article (object) saved $user: the user (object) who saved the article @@ -286,11 +325,22 @@ $isminor: minor flag $iswatch: watch flag $section: section # +wfRunHooks( 'ArticleSaveComplete', array( &$this, &$wgUser, $text, $summary, $flags & EDIT_MINOR, null, null, &$flags, $revision ) ); + 'ArticleUndeleted': When one or more revisions of an article are restored $title: Title corresponding to the article restored $create: Whether or not the restoration caused the page to be created (i.e. it didn't exist before) +'ArticleViewHeader': Before the parser cache is about to be tried for article viewing. +&$pcache: whether to try the parser cache or not +&$outputDone: whether the output for this page finished or not + +'ArticleUpdateBeforeRedirect': After a page is updated (usually on save), before the user is redirected back to the page +&$article: the article +&$sectionanchor: The section anchor link (e.g. "#overview" ) +&$extraq: Extra query parameters which can be added via hooked functions + 'AuthPluginSetup': update or replace authentication plugin object ($wgAuth) Gives a chance for an extension to set it programattically to a variable class. &$auth: the $wgAuth object, probably a stub @@ -305,6 +355,30 @@ $name: Image name being checked Change $bad and return false to override. If an image is "bad", it is not rendered inline in wiki pages or galleries in category pages. +'BeforeGalleryFindFile': before an image is fetched for a gallery +&$gallery,: the gallery object +&$nt: the image title +&$time: image timestamp + +'BeforePageDisplay': Prior to outputting a page +$out: OutputPage object + +'BeforeParserFetchTemplateAndtitle': before a template is fetched by Parser +&$parser: Parser object +&$title: title of the template +&$skip: skip this template and link it? +&$id: the id of the revision being parsed + +'BeforeParserMakeImageLinkObj': before an image is rendered by Parser +&$parser: Parser object +&$nt: the image title +&$skip: skip this image and link it? +&$time: the image timestamp + +'BeforeParserrenderImageGallery': before an image gallery is rendered by Parser +&$parser: Parser object +&$ig: ImageGallery object + 'BlockIp': before an IP address or user is blocked $block: the Block object about to be saved $user: the user _doing_ the block (not the one being blocked) @@ -317,6 +391,14 @@ $user: the user who did the block (not the one being blocked) $isbn: ISBN to show information for $output: OutputPage object in use +'CategoryPageView': before viewing a categorypage in CategoryPage::view +$catpage: CategoryPage instance + +'ContributionsToolLinks': Change tool links above Special:Contributions +$id: User identifier +$title: User page title +&$tools: Array of tool links + 'CustomEditor': When invoking the page editor $article: Article being edited $user: User performing the edit @@ -354,6 +436,21 @@ Alternatively, modifying $error and returning true will cause the contents of $e to be echoed at the top of the edit form as wikitext. Return true without altering $error to allow the edit to proceed. +'EditSectionLink': Override the return value of Linker::editSectionLink() +$skin: Skin rendering the UI +$title: Title being linked to +$section: Section to link to +$link: Default link +$result: Result (alter this to override the generated links) + +'EditSectionLinkForOther': Override the return value of Linker::editSectionLinkForOther() +$skin: Skin rendering the UI +$title: Title being linked to +$section: Section to link to +$hint: Anchor title/tooltip attributes +$link: Default link +$result: Result (alter this to override the generated links) + 'EmailConfirmed': When checking that the user's email address is "confirmed" $user: User being checked $confirmed: Whether or not the email address is confirmed @@ -396,12 +493,34 @@ $title: Title object of page $url: string value as output (out parameter, can modify) $query: query options passed to Title::getFullURL() +'ImageOpenShowImageInlineBefore': Call potential extension just before showing the image on an image page +$imagePage: ImagePage object ($this) +$output: $wgOut + +'InitPreferencesForm': called at the end of PreferencesForm's constructor +$form: the PreferencesForm +$request: the web request to initialized from + 'InternalParseBeforeLinks': during Parser's internalParse method before links but after noinclude/includeonly/onlyinclude and other processing. &$this: Parser object &$text: string containing partially parsed text &$this->mStripState: Parser's internal StripState object +'isValidPassword': Override the result of User::isValidPassword() +$password: Desired password +&$result: Set this and return false to override the internal checks +$user: User the password is being validated for + +'LinksUpdateConstructed': At the end of LinksUpdate() is contruction. +&$linksUpdate: the LinkUpdate object + +'LoginAuthenticateAudit': a login attempt for a valid user account either succeeded or failed. + No return data is accepted; this hook is for auditing only. +$user: the User object being authenticated against +$password: the password being submitted and found wanting +$retval: a LoginForm class constant with authenticateUserData() return value (SUCCESS, WRONG_PASS, etc) + 'LogPageValidTypes': action being logged. DEPRECATED: Use $wgLogTypes &$type: array of strings @@ -474,12 +593,31 @@ $form : PreferencesForm object &$obj: RawPage object &$text: The text that's going to be the output +'RenderPreferencesForm': called at the end of PreferencesForm::mainPrefsForm +$form: the PreferencesForm +$out: output page to render to, probably $wgOut + +'ResetPreferences': called at the end of PreferencesForm::resetPrefs +$form: the PreferencesForm +$user: the User object to load preferences from + +'SavePreferences': called at the end of PreferencesForm::savePreferences; + returning false prevents the preferences from being saved. +$form: the PreferencesForm +$user: the User object to save preferences to +$message: change this to set an error message (ignored if the hook does notreturn fals) + 'SearchUpdate': Prior to search update completion $id : Page id $namespace : Page namespace $title : Page title $text : Current text being indexed +'ShowRawCssJs': Customise the output of raw CSS and JavaScript in page views +$text: Text being shown +$title: Title of the custom script/stylesheet page +$output: Current OutputPage object + 'SiteNoticeBefore': Before the sitenotice/anonnotice is composed &$siteNotice: HTML returned as the sitenotice Return true to allow the normal method of notice selection/rendering to work, @@ -489,10 +627,23 @@ or change the value of $siteNotice and return false to alter it. &$siteNotice: HTML sitenotice Alter the contents of $siteNotice to add to/alter the sitenotice/anonnotice. +'SkinAfterBottomScripts': At the end of Skin::bottomScripts() +$skin: Skin object +&$text: bottomScripts Text +Append to $text to add additional text/scripts after the stock bottom scripts. + +'SkinTemplateContentActions': Alter the "content action" links in SkinTemplates +&$content_actions: Content actions +[See http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/examples/Content_action.php +for an example] + 'SkinTemplateOutputPageBeforeExec': Before SkinTemplate::outputPage() starts page output &$sktemplate: SkinTemplate object &$tpl: Template engine object +'SpecialContributionsBeforeMainOutput': Before the form on Special:Contributions +$id: User identifier + 'TitleMoveComplete': after moving an article (title) $old: old title $nt: new title @@ -513,6 +664,10 @@ $article: article object to be removed $user: user that was watching $article: article object removed +'UnwatchArticleComplete': after a watch is removed from an article +$user: user that watched +$article: article object that was watched + 'UploadForm:initial': before the upload form is generated $form: UploadForm object You might set the member-variables $uploadFormTextTop and @@ -559,6 +714,17 @@ $user : User object that was changed $add : Array of strings corresponding to groups added $remove: Array of strings corresponding to groups removed +'UserGetImplicitGroups': Called in User::getImplicitGroups() +&$groups: List of implicit (automatically-assigned) groups + +'UserGetRights': Called in User::getRights() +$user: User to get rights for +&$rights: Current rights + +'UserEffectiveGroups': Called in User::getEffectiveGroups() +$user: User to get groups for +&$groups: Current effective groups + 'WatchArticle': before a watch is added to an article $user: user that will watch $article: article object to be watched @@ -567,28 +733,6 @@ $article: article object to be watched $user: user that watched $article: article object watched -'UnwatchArticleComplete': after a watch is removed from an article -$user: user that watched -$article: article object that was watched - -'CategoryPageView': before viewing a categorypage in CategoryPage::view -$catpage: CategoryPage instance - -'SkinTemplateContentActions': after building the $content_action array right - before returning it, see Content_action.php in - the extensions/examples/ directory - ( http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/examples/ ) - for a demonstration of how to use this hook. -$content_actions: The array of content actions - -'BeforePageDisplay': Called just before outputting a page (all kinds of, - articles, special, history, preview, diff, edit, ...) - Can be used to set custom CSS/JS -$out: OutputPage object - -'AjaxAddScript': Called in output page just before the initialisation -of the javascript ajax engine. The hook is only called when ajax -is enabled ( $wgUseAjax = true; ). More hooks might be available but undocumented, you can execute -./maintenance/findhooks.php to find hidden one. +./maintenance/findhooks.php to find hidden one. \ No newline at end of file diff --git a/docs/memcached.txt b/docs/memcached.txt index d4e2915f..3addd965 100644 --- a/docs/memcached.txt +++ b/docs/memcached.txt @@ -53,7 +53,7 @@ on port 11000, using up to 64MB of memory) In your LocalSettings.php file, set: - $wgMainCacheType = CACHE_MEMCACHED;; + $wgMainCacheType = CACHE_MEMCACHED; $wgMemCachedServers = array( "127.0.0.1:11000" ); The wiki should then use memcached to cache various data. To use diff --git a/docs/schema.txt b/docs/schema.txt index f7348462..365576cc 100644 --- a/docs/schema.txt +++ b/docs/schema.txt @@ -4,3 +4,6 @@ which is called from the installation script. That file has been commented with details of the usage for each table and field. + +Historical information and some other notes are available at +http://www.mediawiki.org/wiki/Manual:Database_layout diff --git a/docs/title.txt b/docs/title.txt index 5d9bd417..fd449c54 100644 --- a/docs/title.txt +++ b/docs/title.txt @@ -10,15 +10,15 @@ attributes of the title. This is intended to be an immutable "value" class, so there are no mutator functions. To get a new instance, call one of the static factory -methods WikiTitle::newFromURL(), WikiTitle::newFromDBKey(), -or WikiTitle::newFromText(). Once instantiated, the +methods Title::newFromURL(), Title::newFromDBKey(), +or Title::newFromText(). Once instantiated, the other non-static accessor methods can be used, such as getText(), getDBKey(), getNamespace(), etc. -The prefix rules: a title consists of an optional Interwiki +The prefix rules: a title consists of an optional interwiki prefix (such as "m:" for meta or "de:" for German), followed by an optional namespace, followed by the remainder of the -title. Both Interwiki prefixes and namespace prefixes have +title. Both interwiki prefixes and namespace prefixes have the same rules: they contain only letters, digits, space, and underscore, must start with a letter, are case insensitive, and spaces and underscores are interchangeable. Prefixes end @@ -74,4 +74,3 @@ it returns 0. For all external articles it returns 0. All of the IDs for all instances of Title created during a request are cached, so they can be looked up quickly while rendering wiki text with lots of internal links. - -- cgit v1.2.3-54-g00ecf