From 370e83bb0dfd0c70de268c93bf07ad5ee0897192 Mon Sep 17 00:00:00 2001 From: Pierre Schmitz Date: Fri, 15 Aug 2008 01:29:47 +0200 Subject: Update auf 1.13.0 --- docs/README | 19 +- docs/database.txt | 7 +- docs/deferred.txt | 59 ++++--- docs/design.txt | 188 +++++++++----------- docs/globals.txt | 69 ++++---- docs/hooks.txt | 500 ++++++++++++++++++++++++++++++++++++++++------------- docs/html/README | 4 +- docs/language.txt | 37 ++-- docs/linkcache.txt | 32 ++-- docs/magicword.txt | 86 ++++++--- docs/memcached.txt | 233 +++++++++++++++++++------ docs/scripts.txt | 63 +++++++ docs/skin.txt | 102 +++++++---- docs/title.txt | 123 ++++++------- 14 files changed, 1012 insertions(+), 510 deletions(-) create mode 100644 docs/scripts.txt (limited to 'docs') diff --git a/docs/README b/docs/README index 1ec3986b..69170767 100644 --- a/docs/README +++ b/docs/README @@ -1,17 +1,16 @@ -[May 31st 2007] +[July 22nd 2008] -The 'docs' directory contain various text files that should help you -understand the most importants classes in MediaWiki. +The 'docs' directory contain various text files that should help you understand +the most important parts of the code of MediaWiki. More in-depth documentation +can be found at http://www.mediawiki.org/wiki/Manual:Code. 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 -in the ../maintenance/ directory. +You can get a fresh version using 'make doc' or mwdocgen.php in the +../maintenance/ directory. - -For end user / administrators, most of the documentation -is located online at: - http://www.mediawiki.org/wiki/Project:Help - +For end user / administrators, most of the documentation is located online at: + http://www.mediawiki.org/wiki/Help:Contents + http://www.mediawiki.org/wiki/Manual:Contents diff --git a/docs/database.txt b/docs/database.txt index 80044734..60e268c5 100644 --- a/docs/database.txt +++ b/docs/database.txt @@ -158,12 +158,9 @@ enclose small groups of queries in their own transaction. Use the following syntax: $dbw = wfGetDB( DB_MASTER ); -$dbw->immediateBegin(); +$dbw->begin(); /* Do queries */ -$dbw->immediateCommit(); - -There are functions called begin() and commit() but they don't do what -you would expect. Don't use them. +$dbw->commit(); Use of locking reads (e.g. the FOR UPDATE clause) is not advised. They are poorly implemented in InnoDB and will cause regular deadlock errors. diff --git a/docs/deferred.txt b/docs/deferred.txt index 06155c56..495e6594 100644 --- a/docs/deferred.txt +++ b/docs/deferred.txt @@ -1,27 +1,36 @@ - deferred.txt -A few of the database updates required by various functions here -can be deferred until after the result page is displayed to the -user. For example, updating the view counts, updating the -linked-to tables after a save, etc. PHP does not yet have any -way to tell the server to actually return and disconnect while -still running these updates (as a Java servelet could), but it -might have such a feature in the future. - -We handle these by creating a deferred-update object (in a real -O-O language these would be classes that implement an interface) -and putting those objects on a global list, then executing the -whole list after the page is displayed. We don't do anything -smart like collating updates to the same table or such because -the list is almost always going to have just one item on it, if -that, so it's not worth the trouble. - - -Since 1.6 there is a 'job queue' in the jobs table, which is used -to update link tables of transcluding pages after edits; this -may be extended in the future to more general background tasks. - -Job queue items are fetched out of the queue and run either -at a random rate during regular page views (by default) or by -a batch process which can be run via maintenance/runJobs.php. +A few of the database updates required by various functions here can be +deferred until after the result page is displayed to the user. For example, +updating the view counts, updating the linked-to tables after a save, etc. PHP +does not yet have any way to tell the server to actually return and disconnect +while still running these updates (as a Java servelet could), but it might have +such a feature in the future. + +We handle these by creating a deferred-update object and putting those objects +on a global list, then executing the whole list after the page is displayed. We +don't do anything smart like collating updates to the same table or such +because the list is almost always going to have just one item on it, if that, +so it's not worth the trouble. + +Since 1.6 there is a 'job queue' in the jobs table, which is used to update +link tables of transcluding pages after edits; this may be extended in the +future to more general background tasks. + +Job queue items are fetched out of the queue and run either at a random rate +during regular page views (by default) or by a batch process which can be run +via maintenance/runJobs.php. + +Currently there are a few different types of jobs: + + refreshLinks + Used to refresh the database tables that store the links between pages. + When a page is changed, all pages using that page are also cleared by + inserting a new job for all those pages. Each job refreshes only one page. + + htmlCacheUpdate + Clear caches when a template is changed to ensure that changes can be seen. + Each job clears $wgUpdateRowsPerJob pages (500 by default). + + enotifNotify + Used when $wgEnotifUseJobQ is true to send mail using the job queue. diff --git a/docs/design.txt b/docs/design.txt index 1a35d5b0..d1904e1e 100644 --- a/docs/design.txt +++ b/docs/design.txt @@ -1,128 +1,110 @@ +design.txt + This is a brief overview of the new design. More thorough and up-to-date information is available on the documentation wiki at http://www.mediawiki.org/ -Primary source files/objects: - - index.php - Main script. It creates the necessary global objects and parses - the URL to determine what to do, which it then generally passes - off to somebody else (depending on the action to be taken). - - All of the functions to which it might delegate generally do - their job by sending content to the $wgOut object. After returning, - the script flushes that out by calling $wgOut->output(). If there - are any changes that need to be made to the database that can be - deferred until after page display, those happen at the end. - - Note that the order in the includes is touchy; Language uses - some global functions, etc. Likewise with the creation of the - global variables. Don't move them around without some forethought. +Primary classes: User - Encapsulates the state of the user viewing/using the site. - Can be queried for things like the user's settings, name, etc. - Handles the details of getting and saving to the "user" table - of the database, and dealing with sessions and cookies. - More details in USER.TXT. + Encapsulates the state of the user viewing/using the site. Can be queried + for things like the user's settings, name, etc. Handles the details of + getting and saving to the "user" table of the database, and dealing with + sessions and cookies. OutputPage - Encapsulates the entire HTML page that will be sent in - response to any server request. It is used by calling its - functions to add text, headers, etc., in any order, and then - 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. + Encapsulates the entire HTML page that will be sent in response to any + server request. It is used by calling its functions to add text, headers, + etc., in any order, and then 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. Title - Represents the title of an article, and does all the work - of translating among various forms such as plain text, URL, - database key, etc. For convenience, and for historical - reasons, it also represents a few features of articles that - don't involve their text, such as access rights. + Represents the title of an article, and does all the work of translating + among various forms such as plain text, URL, database key, etc. For + convenience, and for historical reasons, it also represents a few features + of articles that don't involve their text, such as access rights. + See also title.txt. Article - Encapsulates access to the "page" table of the database. The - object represents a an article, and maintains state such as - text (in Wikitext format), flags, etc. + Encapsulates access to the "page" table of the database. The object + represents a an article, and maintains state such as text (in Wikitext + format), flags, etc. Revision Encapsulates individual page revision data and access to the - revision/text/blobs storage system. Higher-level code should - never touch text storage directly; this class mediates it. + revision/text/blobs storage system. Higher-level code should never touch + text storage directly; this class mediates it. Skin - Encapsulates a "look and feel" for the wiki. All of the - functions that render HTML, and make choices about how to - render it, are here, and are called from various other - places when needed (most notably, OutputPage::addWikiText()). - The StandardSkin object is a complete implementation, and is - meant to be subclassed with other skins that may override - some of its functions. The User object contains a reference - to a skin (according to that user's preference), and so - rather than having a global skin object we just rely on the - global User and get the skin with $wgUser->getSkin(). + Encapsulates a "look and feel" for the wiki. All of the functions that + render HTML, and make choices about how to render it, are here, and are + called from various other places when needed (most notably, + OutputPage::addWikiText()). The StandardSkin object is a complete + implementation, and is meant to be subclassed with other skins that may + override some of its functions. The User object contains a reference to a + skin (according to that user's preference), and so rather than having a + global skin object we just rely on the global User and get the skin with + $wgUser->getSkin(). + See also skin.txt. Language - Represents the language used for incidental text, and also - has some character encoding functions and other locale stuff. - 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. + Represents the language used for incidental text, and also has some + character encoding functions and other locale stuff. 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. + See also language.txt. + + Parser + Class used to transform wikitext to html. LinkCache - Keeps information on existence of articles. See LINKCACHE.TXT. + Keeps information on existence of articles. See linkcache.txt. Naming/coding conventions: - These are meant to be descriptive, not dictatorial; I won't - presume to tell you how to program, I'm just describing the - methods I chose to use for myself. If you do choose to - follow these guidelines, it will probably be easier for you - to collaborate with others on the project, but if you want - to contribute without bothering, by all means do so (and don't - be surprised if I reformat your code). - - - I have the code indented with tabs to save file size and - so that users can set their tab stops to any depth they like. - I use 4-space tab stops, which work well. I also use K&R brace - matching style. I know that's a religious issue for some, - so if you want to use a style that puts opening braces on the - next line, that's OK too, but please don't use a style where - closing braces don't align with either the opening brace on - its own line or the statement that opened the block--that's - confusing as hell. - - - 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 - required "$this->", which PHP will happily accept by creating - a new local variable rather than complaining. - - - Globals are particularly evil in PHP; it sets a lot of them - automatically from cookies, query strings, and such, leading to - namespace conflicts; when a variable name is used in a function, - it is silently declared as a new local masking the global, so - you'll get weird error because you forgot the global declaration; - lack of static class member variables means you have to use - globals for them, etc. Evil, evil. - - I think I've managed to pare down the number of globals we use - to a scant few dozen or so, and I've prefixed them all with "wg" - so you can spot errors better (odds are, if you see a "wg" - variable being used in a function that doesn't declare it global, - that's probably an error). - - Other conventions: Top-level functions are wfFuncname(), names - of session variables are wsName, cookies wcName, and form field - values wpName ("p" for "POST"). \ No newline at end of file + These are meant to be descriptive, not dictatorial; I won't presume to tell + you how to program, I'm just describing the methods I chose to use for myself. + If you do choose to follow these guidelines, it will probably be easier for + you to collaborate with others on the project, but if you want to contribute + without bothering, by all means do so (and don't be surprised if I reformat + your code). + + - I have the code indented with tabs to save file size and so that users can + set their tab stops to any depth they like. I use 4-space tab stops, which + work well. I also use K&R brace matching style. I know that's a religious + issue for some, so if you want to use a style that puts opening braces on + the next line, that's OK too, but please don't use a style where closing + braces don't align with either the opening brace on its own line or the + statement that opened the block--that's confusing as hell. + + - 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 required "$this->", which PHP + will happily accept by creating a new local variable rather than complaining. + + - Globals are particularly evil in PHP; it sets a lot of them automatically + from cookies, query strings, and such, leading to namespace conflicts; when + a variable name is used in a function, it is silently declared as a new + local masking the global, so you'll get weird error because you forgot the + global declaration; lack of static class member variables means you have to + use globals for them, etc. Evil, evil. + + I think I've managed to pare down the number of globals we use to a scant + few dozen or so, and I've prefixed them all with "wg" so you can spot errors + better (odds are, if you see a "wg" variable being used in a function that + doesn't declare it global, that's probably an error). + + Other conventions: Top-level functions are wfFuncname(), names of session + variables are wsName, cookies wcName, and form field values wpName ("p" for + "POST"). diff --git a/docs/globals.txt b/docs/globals.txt index 8320eec0..46486dd8 100644 --- a/docs/globals.txt +++ b/docs/globals.txt @@ -1,12 +1,10 @@ globals.txt -Globals are evil. The original MediaWiki code relied on -globals for processing context far too often. MediaWiki -development since then has been a story of slowly moving -context out of global variables and into objects. Storing -processing context in object member variables allows those -objects to be reused in a much more flexible way. Consider -the elegance of: +Globals are evil. The original MediaWiki code relied on globals for processing +context far too often. MediaWiki development since then has been a story of +slowly moving context out of global variables and into objects. Storing +processing context in object member variables allows those objects to be reused +in a much more flexible way. Consider the elegance of: # Generate the article HTML as if viewed by a web request $article = new Article( Title::newFromText( $t ) ); @@ -27,51 +25,43 @@ versus $wgTitle = $oldTitle $wgArticle = $oldArticle -Some of the current MediaWiki developers have an idle -fantasy that some day, globals will be eliminated from -MediaWiki entirely, replaced by an application object which -would be passed to constructors. Whether that would be an -efficient, convenient solution remains to be seen, but -certainly PHP 5 makes such object-oriented programming -models easier than they were in previous versions. - -For the time being though, MediaWiki programmers will have -to work in an environment with some global context. At the -time of writing, 418 globals were initialised on startup by -MediaWiki. 304 of these were configuration settings, which -are documented in DefaultSettings.php. There is no -comprehensive documentation for the remaining 114 globals, -however some of the most important ones are listed below. -They are typically initialised either in index.php or in +Some of the current MediaWiki developers have an idle fantasy that some day, +globals will be eliminated from MediaWiki entirely, replaced by an application +object which would be passed to constructors. Whether that would be an +efficient, convenient solution remains to be seen, but certainly PHP 5 makes +such object-oriented programming models easier than they were in previous +versions. + +For the time being though, MediaWiki programmers will have to work in an +environment with some global context. At the time of writing, 418 globals were +initialised on startup by MediaWiki. 304 of these were configuration settings, +which are documented in DefaultSettings.php. There is no comprehensive +documentation for the remaining 114 globals, however some of the most important +ones are listed below. They are typically initialised either in index.php or in Setup.php. +For a description of the classes, see design.txt. + +$wgTitle + Title object created from the request URL. + +$wgArticle + Article object corresponding to $wgTitle. $wgOut OutputPage object for HTTP response. $wgUser - User object for the user associated with the current - request. - -$wgTitle - Title object created from the request URL. + User object for the user associated with the current request. $wgLang - Language object selected by user preferences + Language object selected by user preferences. $wgContLang - Language object associated with the wiki being - viewed. - -$wgArticle - Article object corresponding to $wgTitle. + Language object associated with the wiki being viewed. $wgParser - Parser object. Parser extensions register their - hooks here. - -$wgLoadBalancer - A LoadBalancer object, manages database connections. + Parser object. Parser extensions register their hooks here. $wgRequest WebRequest object, to get request data @@ -81,4 +71,3 @@ $wgMemc, $messageMemc, $parserMemc $wgMessageCache Message cache, to manage interface messages - diff --git a/docs/hooks.txt b/docs/hooks.txt index 9e27a8d0..286ed7e2 100644 --- a/docs/hooks.txt +++ b/docs/hooks.txt @@ -1,39 +1,38 @@ hooks.txt -This document describes how event hooks work in MediaWiki; how to add -hooks for an event; and how to run hooks for an event. +This document describes how event hooks work in MediaWiki; how to add hooks for +an event; and how to run hooks for an event. ==Glossary== event - Something that happens with the wiki. For example: a user logs - in. A wiki page is saved. A wiki page is deleted. Often there are - two events associated with a single action: one before the code - is run to make the event happen, and one after. Each event has a - name, preferably in CamelCase. For example, 'UserLogin', - 'ArticleSave', 'ArticleSaveComplete', 'ArticleDelete'. + Something that happens with the wiki. For example: a user logs in. A wiki + page is saved. A wiki page is deleted. Often there are two events + associated with a single action: one before the code is run to make the + event happen, and one after. Each event has a name, preferably in + CamelCase. For example, 'UserLogin', 'ArticleSave', 'ArticleSaveComplete', + 'ArticleDelete'. hook - A clump of code and data that should be run when an event - happens. This can be either a function and a chunk of data, or an - object and a method. + A clump of code and data that should be run when an event happens. This can + be either a function and a chunk of data, or an object and a method. hook function The function part of a hook. ==Rationale== -Hooks allow us to decouple optionally-run code from code that is run -for everyone. It allows MediaWiki hackers, third-party developers and -local administrators to define code that will be run at certain points -in the mainline code, and to modify the data run by that mainline -code. Hooks can keep mainline code simple, and make it easier to -write extensions. Hooks are a principled alternative to local patches. +Hooks allow us to decouple optionally-run code from code that is run for +everyone. It allows MediaWiki hackers, third-party developers and local +administrators to define code that will be run at certain points in the mainline +code, and to modify the data run by that mainline code. Hooks can keep mainline +code simple, and make it easier to write extensions. Hooks are a principled +alternative to local patches. -Consider, for example, two options in MediaWiki. One reverses the -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): +Consider, for example, two options in MediaWiki. One reverses the 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; @@ -49,31 +48,30 @@ would handle this as follows (note: not real code, here): # 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: +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: function showAnArticle($article) { - global $wgReverseTitle, $wgCapitalizeTitle; + global $wgReverseTitle, $wgCapitalizeTitle, $wgNotifyArticle; - if ($wgReverseTitle) { - wfReverseTitle($article); - } + if ($wgReverseTitle) { + wfReverseTitle($article); + } - if ($wgCapitalizeTitle) { - wfCapitalizeTitle($article); - } + if ($wgCapitalizeTitle) { + wfCapitalizeTitle($article); + } - # code to actually show the article goes here + # code to actually show the article goes here - if ($wgNotifyArticle) { - wfNotifyArticleShow($article)); - } + if ($wgNotifyArticle) { + wfNotifyArticleShow($article)); + } } -Using a hook-running strategy, we can avoid having all this -option-specific stuff in our mainline code. Using hooks, the function -becomes: +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) { @@ -85,16 +83,15 @@ becomes: } } -We've cleaned up the code here by removing clumps of weird, -infrequently used code and moving them off somewhere else. It's much -easier for someone working with this code to see what's _really_ going -on, and make changes or fix bugs. +We've cleaned up the code here by removing clumps of weird, infrequently used +code and moving them off somewhere else. It's much easier for someone working +with this code to see what's _really_ going on, and make changes or fix bugs. -In addition, we can take all the code that deals with the little-used -title-reversing options (say) and put it in one place. Instead of -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: +In addition, we can take all the code that deals with the little-used +title-reversing options (say) and put it in one place. Instead of 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) { # ... @@ -104,8 +101,8 @@ concentrate it all in an extension file: # ... } -The setup function for the extension just has to add its hook -functions to the appropriate events: +The setup function for the extension just has to add its hook functions to the +appropriate events: setupTitleReversingExtension() { global $wgHooks; @@ -115,23 +112,21 @@ functions to the appropriate events: $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 -do a grep-find to see where the $wgReverseTitle variable is used, say. +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 do a grep-find to see +where the $wgReverseTitle variable is used, say. -If the code is well enough isolated, it can even be excluded when not -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: +If the code is well enough isolated, it can even be excluded when not 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'); -...to their LocalSettings.php file; those of us who don't want or need -it can just leave it out. +...to their LocalSettings.php file; those of us who don't want or need it can +just leave it out. -The extensions don't even have to be shipped with MediaWiki; they -could be provided by a third-party developer or written by the admin -him/herself. +The extensions don't even have to be shipped with MediaWiki; they could be +provided by a third-party developer or written by the admin him/herself. ==Writing hooks== @@ -140,8 +135,8 @@ A hook is a chunk of code run at some particular event. It consists of: * a function with some optional accompanying data, or * an object with a method and some optional accompanying data. -Hooks are registered by adding them to the global $wgHooks array for a -given event. All the following are valid ways to define hooks: +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); @@ -152,10 +147,9 @@ given event. All the following are valid ways to define hooks: $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: +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) @@ -169,31 +163,30 @@ when 'EventName' happened: # 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 -would be different: 'onArticleSave', 'onUserLogin', etc. +Note that when an object is the hook, and there's no specified method, the +default method called is 'onEventName'. For different events this 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: +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'); -This code would result in ircNotify being run twice when an article is -saved: once for 'TimStarling', and once for 'brion'. +This code would result in ircNotify being run twice when an article is saved: +once for 'TimStarling', and once for 'brion'. Hooks can return three possible values: * true: the hook has operated successfully - * "some string": an error occurred; processing should - stop and the error should be shown to the user - * false: the hook has successfully done the work - necessary and the calling function should skip + * "some string": an error occurred; processing should stop and the error + should be shown to the user + * false: the hook has successfully done the work necessary and the calling + function should skip -The last result would be for cases where the hook function replaces -the main functionality. For example, if you wanted to authenticate -users to a custom system (LDAP, another PHP program, whatever), you -could do: +The last result would be for cases where the hook function replaces 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); @@ -202,13 +195,13 @@ could do: return false; } -Returning false makes less sense for events where the action is -complete, and will normally be ignored. +Returning false makes less sense for events where the action is complete, and +will normally be ignored. ==Using hooks== -A calling function or method uses the wfRunHooks() function to run -the hooks related to a particular event, like so: +A calling function or method uses the wfRunHooks() function to run the hooks +related to a particular event, like so: class Article { # ... @@ -221,22 +214,25 @@ the hooks related to a particular event, like so: } } -wfRunHooks() returns true if the calling function should continue -processing (the hooks ran OK, or there are no hooks to run), or false -if it shouldn't (an error occurred, or one of the hooks handled the -action already). Checking the return value matters more for "before" -hooks than for "complete" hooks. +wfRunHooks() returns true if the calling function should continue processing +(the hooks ran OK, or there are no hooks to run), or false if it shouldn't (an +error occurred, or one of the hooks handled the action already). Checking the +return value matters more for "before" hooks than for "complete" hooks. Note that hook parameters are passed in an array; this is a necessary -inconvenience to make it possible to pass reference values (that can -be changed) into the hook code. Also note that earlier versions of -wfRunHooks took a variable number of arguments; the array() calling -protocol came about after MediaWiki 1.4rc1. +inconvenience to make it possible to pass reference values (that can be changed) +into the hook code. Also note that earlier versions of wfRunHooks took a +variable number of arguments; the array() calling protocol came about after +MediaWiki 1.4rc1. ==Events and parameters== -This is a list of known events and parameters; please add to it if -you're going to add events to the MediaWiki code. +This is a list of known events and parameters; please add to it if you're going +to add events to the MediaWiki code. + +'AbortAutoblock': Return false to cancel an autoblock. +$autoblockip: The IP going to be autoblocked. +$block: The block from which the autoblock is coming. 'AbortLogin': Return false to cancel account login. $user: the User object being authenticated against @@ -250,6 +246,7 @@ $old: old title $nt: new title $user: user who is doing the move $err: error message +$reason: the reason for the move (added in 1.13) 'AbortNewAccount': Return false to cancel account creation. $user: the User object about to be created (read-only, incomplete) @@ -268,6 +265,36 @@ before showing the edit form ( EditPage::edit() ). This is triggered on &action=edit. $EditPage : the EditPage object +'APIEditBeforeSave': before saving a page with api.php?action=edit, +after processing request parameters. Return false to let the request +fail, returning an error message or an tag +if $resultArr was filled. +$EditPage : the EditPage object +$text : the new text of the article (has yet to be saved) +$resultArr : data in this array will be added to the API result + +'APIQueryInfoTokens': use this hook to add custom tokens to prop=info. +Every token has an action, which will be used in the intoken parameter +and in the output (actiontoken="..."), and a callback function which +should return the token, or false if the user isn't allowed to obtain +it. The prototype of the callback function is func($pageid, $title) +where $pageid is the page ID of the page the token is requested for +and $title is the associated Title object. In the hook, just add +your callback to the $tokenFunctions array and return true (returning +false makes no sense) +$tokenFunctions: array(action => callback) + +'APIQueryRevisionsTokens': use this hook to add custom tokens to prop=revisions. +Every token has an action, which will be used in the rvtoken parameter +and in the output (actiontoken="..."), and a callback function which +should return the token, or false if the user isn't allowed to obtain +it. The prototype of the callback function is func($pageid, $title, $rev) +where $pageid is the page ID of the page associated to the revision the +token is requested for, $title the associated Title object and $rev the +associated Revision object. In the hook, just add your callback to the +$tokenFunctions array and return true (returning false makes no sense) +$tokenFunctions: array(action => callback) + 'ArticleAfterFetchContent': after fetching content of an article from the database $article: the article (object) being loaded from the database $content: the content (string) of the article @@ -276,11 +303,14 @@ $content: the content (string) of the article $article: the article (object) being deleted $user: the user (object) deleting the article $reason: the reason (string) the article is being deleted +$error: if the deletion was prohibited, the (raw HTML) error message to display + (added in 1.13) 'ArticleDeleteComplete': after an article is deleted $article: the article that was deleted $user: the user that deleted the article $reason: the reason the article was deleted +$id: id of the article that was deleted 'ArticleEditUpdateNewTalk': before updating user_newtalk when a user talk page was changed $article: article (object) of the user talk page @@ -292,7 +322,7 @@ $article: article (object) being modified $title: title (object) used to create the article object $article: article (object) that will be returned -'ArticleInsertComplete': After an article is created +'ArticleInsertComplete': After a new article is created $article: Article created $user: User creating the article $text: New content @@ -332,7 +362,11 @@ $moveonly: boolean whether it was for move only or not 'ArticlePurge': before executing "&action=purge" $article: article (object) to purge -'ArticleRevisionUndeleted' after an article revision is restored +'ArticleRevisionVisiblitySet': called when changing visibility of one or more +revision of an article +&$title: title object of the article + +'ArticleRevisionUndeleted': after an article revision is restored $title: the article title $revision: the revision $oldPageID: the page ID of the revision when archived (may be null) @@ -391,13 +425,14 @@ $create: Whether or not the restoration caused the page to be created 'ArticleViewRedirect': before setting "Redirected from ..." subtitle when follwed an redirect $article: target article (object) +'AuthPluginAutoCreate': Called when creating a local account for an user logged +in from an external authentication method +$user: User object created locally + '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 -'AutoAuthenticate': called to authenticate users on external/environmental means -$user: writes user object to this parameter - 'AutopromoteCondition': check autopromote condition for user. $type: condition type $args: arguments @@ -417,7 +452,8 @@ rendered inline in wiki pages or galleries in category pages. &$time: image timestamp 'BeforePageDisplay': Prior to outputting a page -$out: OutputPage object +&$out: OutputPage object +&$skin: Skin object 'BeforeParserFetchTemplateAndtitle': before a template is fetched by Parser &$parser: Parser object @@ -454,6 +490,18 @@ $user: the user who did the block (not the one being blocked) $isbn: ISBN to show information for $output: OutputPage object in use +'BrokenLink': Before the HTML is created for a broken (i.e. red) link +&$linker: Linker instance +$nt: the page title +$query: the URL query string passed in +&$u: the URL of this link +&$style: the inline CSS style +&$prefix: a prefix prepended to the linked text +&$text: the text placed by the user in the wiki-link +&$inside: any additional alphanumeric characters placed after the wiki-link, +that are made part of the link text +&$trail: text placed immediately after the HTML link + 'CategoryPageView': before viewing a categorypage in CategoryPage::view $catpage: CategoryPage instance @@ -465,6 +513,15 @@ $catpage: CategoryPage instance $unpatrolled: Whether or not we are showing unpatrolled changes. $watched: Whether or not the change is watched by the user. +'ContribsPager::getQueryInfo': Before the contributions query is about to run +&$pager: Pager object for contributions +&queryInfo: The query for the contribs Pager + +'ContributionsLineEnding': Called before a contributions HTML line is finished +$page: SpecialPage object for contributions +$ret: the HTML line +$row: the DB row for this line + 'ContributionsToolLinks': Change tool links above Special:Contributions $id: User identifier $title: User page title @@ -492,11 +549,13 @@ $editor: Edit form (see includes/EditPage.php) $text: Contents of the edit box $section: Section being edited &$error: Error message to return +$summary: Edit summary for page 'EditFilterMerged': Post-section-merge edit filter $editor: EditPage instance (object) $text: content of the edit box $error: error message to return +$summary: Edit summary for page 'EditFormPreloadText': Allows population of the edit form when creating new pages &$text: Text to preload with @@ -519,6 +578,14 @@ 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. +'EditPageBeforeConflictDiff': allows modifying the EditPage object and output +when there's an edit conflict. Return false to halt normal diff output; in +this case you're responsible for computing and outputting the entire "conflict" +part, i.e., the "difference between revisions" and "your text" headers and +sections. +&$editor: EditPage instance +&$out: OutputPage instance + 'EditPageBeforeEditButtons': allows modifying the edit buttons below the textarea in the edit form &$editpage: The current EditPage object &$buttons: Array of edit buttons "Save", "Preview", "Live", and "Diff" @@ -562,12 +629,35 @@ $text: text of the mail &$list: List object (defaults to NULL, change it to an object instance and return false override the list derivative used) +'FileDeleteComplete': When a file is deleted +$file: reference to the deleted file +$oldimage: in case of the deletion of an old image, the name of the old file +$article: in case all revisions of the file are deleted a reference to the article + associated with the file. +$user: user who performed the deletion +$reason: reason + 'FileUpload': When a file upload occurs $file : Image object representing the file that was uploaded +'FileUndeleteComplete': When a file is undeleted +$title: title object to the file +$fileVersions: array of undeleted versions. Empty if all versions were restored +$user: user who performed the undeletion +$reason: reason + +'GetAutoPromoteGroups': When determining which autopromote groups a user is entitled to be in. +&$user: user to promote. +&$promote: groups that will be added. + 'GetBlockedStatus': after loading blocking status of an user from the database $user: user (object) being checked +'GetCacheVaryCookies': get cookies that should vary cache options +$out: OutputPage object +&$cookies: array of cookies name, add a value to it if you want to add a cookie + that have to vary cache options + 'GetFullURL': modify fully-qualified URLs used in redirects/export/offsite data $title: Title object of page $url: string value as output (out parameter, can modify) @@ -602,10 +692,41 @@ $result: User permissions error to add. If none, return true. 'getUserPermissionsErrorsExpensive': Absolutely the same, but is called only if expensive checks are enabled. -'ImageOpenShowImageInlineBefore': Call potential extension just before showing the image on an image page +'ImageBeforeProduceHTML': Called before producing the HTML created by a wiki + image insertion. You can skip the default logic entirely by returning + false, or just modify a few things using call-by-reference. +&$this: Skin object +&$title: Title object of the image +&$file: File object, or false if it doesn't exist +&$frameParams: Various parameters with special meanings; see documentation in + includes/Linker.php for Linker::makeImageLink2 +&$handlerParams: Various parameters with special meanings; see documentation in + includes/Linker.php for Linker::makeImageLink2 +&$time: Timestamp of file in 'YYYYMMDDHHIISS' string form, or false for current +&$res: Final HTML output, used if you return false + + +'ImageOpenShowImageInlineBefore': Call potential extension just before showing + the image on an image page $imagePage: ImagePage object ($this) $output: $wgOut +'ImagePageFileHistoryLine': called when a file history line is contructed +$file: the file +$line: the HTML of the history line +$css: the line CSS class + +'ImagePageFindFile': called when fetching the file associated with an image page +$page: ImagePage object +&$file: File object +&$displayFile: displayed File object + +'InitializeArticleMaybeRedirect': MediaWiki check to see if title is a redirect +$title: Title object ($wgTitle) +$request: WebRequest +$ignoreRedirect: boolean to skip redirect check +$target: Title/string of redirect target + 'InitPreferencesForm': called at the end of PreferencesForm's constructor $form: the PreferencesForm $request: the web request to initialized from @@ -641,6 +762,16 @@ $lang: laguage code (string) $specialPageAliases: associative array of magic words synonyms $lang: laguage code (string) +'LinkerMakeExternalImage': At the end of Linker::makeExternalImage() just before the return +&$url: the image url +&$alt: the image's alt text +&$img: the new image HTML (if returning false) + +'LinkerMakeExternalLink': At the end of Linker::makeExternalLink() just before the return +&$url: the link url +&$text: the link text +&$link: the new link HTML (if returning false) + 'LinksUpdate': At the beginning of LinksUpdate::doUpdate() just before the actual update &$linksUpdate: the LinkUpdate object @@ -654,6 +785,14 @@ $lang: laguage code (string) 'LoadExtensionSchemaUpdates': called by maintenance/updaters.inc when upgrading database schema +'LocalFile::getHistory': called before file history query performed +$file: the file +$tables: tables +$fields: select fields +$conds: conditions +$opts: query options +$join_conds: JOIN conditions + '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 @@ -715,14 +854,35 @@ $article: $wgArticle $title: $wgTitle $user: $wgUser $request: $wgRequest +$this: The $mediawiki object 'MessagesPreLoad': When loading a message from the database $title: title of the message (string) $message: value (string), change it to the message you want to define 'MonoBookTemplateToolboxEnd': Called by Monobook skin after toolbox links have been rendered (useful for adding more) +Note: this is only run for the Monobook skin. To add items to the toolbox +for all 'SkinTemplate'-type skins, use the SkinTemplateToolboxEnd hook +instead. $tools: array of tools +'NewRevisionFromEditComplete': called when a revision was inserted due to an edit +$article: the article edited +$rev: the new revision +$baseID: the revision ID this was based off, if any + +'NormalizeMessageKey': Called before the software gets the text of a message + (stuff in the MediaWiki: namespace), useful for changing WHAT message gets displayed +&$key: the message being looked up. Change this to something else to change what message gets displayed (string) +&$useDB: whether or not to look up the message in the database (bool) +&$langCode: the language code to get the message for (string) - or - + whether to use the content language (true) or site language (false) (bool) +&$transform: whether or not to expand variables and templates in the message (bool) + +'OpenSearchUrls': Called when constructing the OpenSearch description XML. +Hooks can alter or append to the array of URLs for search & suggestion formats. +&$urls: array of associative arrays with Url element attributes + 'OutputPageBeforeHTML': a page has been processed by the parser and the resulting HTML is about to be displayed. $parserOutput: the parserOutput (object) that corresponds to the page @@ -732,6 +892,12 @@ $text: the text that will be displayed, in HTML (string) $out: OutputPage instance (object) $parserOutput: parserOutput instance being added in $out +'OutputPageMakeCategoryLinks': links are about to be generated for the page's categories. + Implementations should return false if they generate the category links, so the default link generation is skipped. +$out: OutputPage instance (object) +$categories: associative array, keys are category names, values are category types ("normal" or "hidden") +$links: array, intended to hold the result. Must be an associative array with category types as keys and arrays of HTML links as values. + 'PageHistoryBeforeList': When a history page list is about to be constructed. $article: the article that the history is loading for @@ -739,6 +905,10 @@ $article: the article that the history is loading for $row: the revision row for this line $s: the string representing this parsed line +'PageHistoryPager::getQueryInfo': when a history pager query parameter set is constructed +$pager: the pager +$queryInfo: the query parameters + 'PageRenderingHash': alter the parser cache option hash key A parser extension which depends on user options should install this hook and append its values to the key. @@ -767,8 +937,8 @@ $text: actual text 'ParserClearState': called at the end of Parser::clearState() $parser: Parser object being cleared -'ParserFirstCallInit': called when the ther parser initialises for the first time -$parser: Parser object being cleared +'ParserFirstCallInit': called when the parser initialises for the first time +&$parser: Parser object being cleared 'ParserGetVariableValueSwitch': called when the parser need the value of a custom magic word $parser: Parser object @@ -788,6 +958,11 @@ $varCache: varaiable cache (array) $parser: Parser object $limitReport: text that will be included (without comment tags) +'ParserMakeImageParams': Called before the parser make an image link, use this to modify the parameters of the image. +$title: title object representing the file +$file: file object that will be used to create the image +&$params: 2-D array of parameters + 'ParserTestParser': called when creating a new instance of Parser in maintenance/parserTests.inc $parser: Parser object created @@ -815,7 +990,7 @@ $form : PreferencesForm object 'PrefixSearchBackend': Override the title prefix search used for OpenSearch and AJAX search suggestions. Put results into &$results outparam and return false. -$ns : int namespace key to search in +$ns : array of int namespace keys to search in $search : search term (not guaranteed to be conveniently normalized) $limit : maximum number of results to return &$results : out param: array of page names (strings) @@ -845,11 +1020,21 @@ $out: output page to render to, probably $wgOut $form: the PreferencesForm $user: the User object to load preferences from +'RevisionInsertComplete': called after a revision is inserted into the DB +&$revision: the Revision +$data: the data stored in old_text. The meaning depends on $flags: if external + is set, it's the URL of the revision text in external storage; otherwise, + it's the revision text itself. In either case, if gzip is set, the revision + text is gzipped. +$flags: a comma-delimited list of strings representing the options used. May + include: utf8 (this will always be set for new revisions); gzip; external. + '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) +$message: change this to set an error message (ignored if the hook does not return false) +$old: old preferences of the user 'SearchUpdate': Prior to search update completion $id : Page id @@ -926,9 +1111,32 @@ $checkEdit: Whether or not the action=edit query should be added if appropriate. $sktemplate: SkinTemplate object $content_actions: array of tabs +'SkinTemplateToolboxEnd': Called by SkinTemplate skins after toolbox links have been rendered (useful for adding more) +$tools: array of tools + 'SpecialContributionsBeforeMainOutput': Before the form on Special:Contributions $id: User identifier +'SpecialListusersDefaultQuery': called right before the end of UsersPager::getDefaultQuery() +$pager: The UsersPager instance +$query: The query array to be returned + +'SpecialListusersFormatRow': called right before the end of UsersPager::formatRow() +$item: HTML to be returned. Will be wrapped in
  • after the hook finishes +$row: Database row object + +'SpecialListusersHeader': called before closing the
    in UsersPager::getPageHeader() +$pager: The UsersPager instance +$out: The header HTML + +'SpecialListusersHeaderForm': called before adding the submit button in UsersPager::getPageHeader() +$pager: The UsersPager instance +$out: The header HTML + +'SpecialListusersQueryInfo': called right before the end of UsersPager::getQueryInfo() +$pager: The UsersPager instance +$query: The query array to be returned + 'SpecialMovepageAfterMove': called after moving a page $movePage: MovePageForm object $oldTitle: old title (object) @@ -955,9 +1163,27 @@ $funct: function called to execute the special page 'SpecialPage_initList': called when setting up SpecialPage::$mList, use this hook to remove a core special page $list: list (array) of core special pages +'SpecialRecentChangesPanel': called when building form options in SpecialRecentChanges +&$extraOpts: array of added items, to which can be added +$opts: FormOptions for this request + +'SpecialRecentChangesQuery': called when building sql query for SpecialRecentChanges +&$conds: array of where conditionals for query +&$tables: array of tables to be queried +&$join_conds: join conditions for the tables +$opts: FormOptions for this request + 'SpecialSearchNogomatch': called when user clicked the "Go" button but the target doesn't exist $title: title object generated from the text entred by the user +'SpecialSearchResults': called before search result display when there are matches +$term: string of search term +&$titleMatches: empty or SearchResultSet object +&$textMatches: empty or SearchResultSet object + +'SpecialSearchNoResults': called before search result display when there are no matches +$term: string of search term + 'SpecialVersionExtensionTypes': called when generating the extensions credits, use this to change the tables headers $extTypes: associative array of extensions types @@ -1006,7 +1232,11 @@ string $tempName: filesystem path to the temporary file for checks string &$error: output: HTML error to show if upload canceled by returning false 'UploadComplete': Upon completion of a file upload -$image: Image object representing the file that was uploaded +$uploadForm: Upload form object. File can be accessed by $uploadForm->mLocalFile. + +'UserArrayFromResult': called when creating an UserArray object from a database result +&$userArray: set this to an object to override the default object returned +$res: database result used to create the object 'userCan': To interrupt/advise the "user can do X to Y article" check. If you want to display an error message, try getUserPermissionsErrors. @@ -1031,8 +1261,35 @@ $template: SimpleTemplate instance for the form $user: User to get groups for &$groups: Current effective groups +'UserGetAllRights': after calculating a list of all available rights +&$rights: Array of rights, which may be added to. + +'UserGetEmail': called when getting an user email address +$user: User object +&$email: email, change this to override local email + +'UserGetEmailAuthenticationTimestamp': called when getting the timestamp of email authentification +$user: User object +&$timestamp: timestamp, change this to override local email authentification timestamp + +'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 + +'UserLoadDefaults': called when loading a default user +$user: user object +$name: user name + +'UserLoadFromSession': called to authenticate users on external/environmental means +$user: user object being loaded +&$result: set this to a boolean value to abort the normal authentification process + 'UserLoginComplete': after a user has logged in $user: the user object that was created on login +$inject_html: Any HTML to inject after the "logged in" message. 'UserLoginForm': change to manipulate the login form $template: SimpleTemplate instance for the form @@ -1042,23 +1299,34 @@ $user: the user object that is about to be logged out 'UserLogoutComplete': after a user has logged out $user: the user object _after_ logout (won't have name, ID, etc.) +$inject_html: Any HTML to inject after the "logged out" message. +$oldName: name of the user before logout (string) 'UserRights': After a user's group memberships are changed $user : User object that was changed $add : Array of strings corresponding to groups added $remove: Array of strings corresponding to groups removed - -'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 'UserRetrieveNewTalks': called when retrieving "You have new messages!" message(s) $user: user retrieving new talks messages $talks: array of new talks page(s) +'UserSaveSettings': called when saving user settings +$user: User object + +'UserSetCookies': called when setting user cookies +$user: User object +&$session: session array, will be added to $_SESSION +&$cookies: cookies array mapping cookie name to its value + +'UserSetEmail': called when changing user email address +$user: User object +&$email: new email, change this to override new email address + +'UserSetEmailAuthenticationTimestamp': called when setting the timestamp of email authentification +$user: User object +&$timestamp: new timestamp, change this to override local email authentification timestamp + 'UserToggles': called when initialising User::$mToggles, use this to add new toggles $toggles: array of toggles to add diff --git a/docs/html/README b/docs/html/README index d25b803d..90de167f 100644 --- a/docs/html/README +++ b/docs/html/README @@ -1,4 +1,4 @@ -This directory is for the auto-generated phpdoc documentation. +This directory is for the auto-generated doxygen documentation. Run 'php mwdocgen.php' in the maintenance subdirectory to build the docs. -Get phpDocumentor from http://phpdoc.org/ +Get Doxygen from http://www.doxygen.org/ diff --git a/docs/language.txt b/docs/language.txt index 9d6a0db3..1df98810 100644 --- a/docs/language.txt +++ b/docs/language.txt @@ -1,24 +1,21 @@ language.txt -The Language object handles all readable text produced by the -software. The most used function is getMessage(), usually -called with the wrapper function wfMsg() which calls that method -on the global language object. It just returns a piece of text -given a text key. It is recommended that you use each key only -once--bits of text in different contexts that happen to be -identical in English may not be in other languages, so it's -better to add new keys than to reuse them a lot. Likewise, -if there is text that gets combined with things like names and -titles, it is better to put markers like "$1" inside a piece -of text and use str_replace() than to compose such messages in -code, because their order may change in other languages too. +The Language object handles all readable text produced by the software. The most +used function is getMessage(), usually called with the wrapper function wfMsg() +which calls that method on the global language object. It just returns a piece +of text given a text key. It is recommended that you use each key only +once--bits of text in different contexts that happen to be identical in English +may not be in other languages, so it's better to add new keys than to reuse them +a lot. Likewise, if there is text that gets combined with things like names and +titles, it is better to put markers like "$1" inside a piece of text and use +str_replace() than to compose such messages in code, because their order may +change in other languages too. -While the system is running, there will be one global language -object, which will be a subtype of Language. The methods in -these objects will return the native text requested if available, -otherwise they fall back to sending English text (which is why -the LanguageEn object has no code at all--it just inherits the -English defaults of the Language base class). +While the system is running, there will be one global language object, which +will be a subtype of Language. The methods in these objects will return the +native text requested if available, otherwise they fall back to sending English +text (which is why the LanguageEn object has no code at all--it just inherits +the English defaults of the Language base class). -The names of the namespaces are also contained in the language -object, though the numbers are fixed. +The names of the namespaces are also contained in the language object, though +the numbers are fixed. diff --git a/docs/linkcache.txt b/docs/linkcache.txt index 3e9799c3..266f200d 100644 --- a/docs/linkcache.txt +++ b/docs/linkcache.txt @@ -1,18 +1,24 @@ linkcache.txt -The LinkCache class maintains a list of article titles and -the information about whether or not the article exists in -the database. This is used to mark up links when displaying -a page. If the same link appears more than once on any page, -then it only has to be looked up once. In most cases, link -lookups are done in batches with the LinkBatch class, or the -equivalent in Parser::replaceLinkHolders(), so the link -cache is mostly useful for short snippets of parsed text -(such as the site notice), and for links in the navigation -areas of the skin. +The LinkCache class maintains a list of article titles and the information about +whether or not the article exists in the database. This is used to mark up links +when displaying a page. If the same link appears more than once on any page, +then it only has to be looked up once. In most cases, link lookups are done in +batches with the LinkBatch class, or the equivalent in Parser::replaceLinkHolders(), +so the link cache is mostly useful for short snippets of parsed text (such as +the site notice), and for links in the navigation areas of the skin. -The link cache was formerly used to track links used in a -document for the purposes of updating the link tables. This -application is now deprecated. +The link cache was formerly used to track links used in a document for the +purposes of updating the link tables. This application is now deprecated. +To create a batch, you can use the following code: +$pages = array( 'Main Page', 'Project:Help', /* ... */ ); +$titles = array(); + +foreach( $pages as $page ){ + $titles[] = Title::newFromText( $page ); +} + +$batch = new LinkBatch( $titles ); +$batch->execute(); \ No newline at end of file diff --git a/docs/magicword.txt b/docs/magicword.txt index 74e49cff..6ecdb569 100644 --- a/docs/magicword.txt +++ b/docs/magicword.txt @@ -1,44 +1,88 @@ magicword.txt -Magic Words are some phrases used in the wikitext. They are defined in several arrays: -* $magicWords (includes/MagicWord.php) includes their internal names ('MAG_XXX'). -* $wgVariableIDs (includes/MagicWord.php) includes their IDs (MAG_XXX, which are constants), - after their internal names are used for "define()". -* Localized arrays (languages/LanguageXX.php) include their different names to be used by the users. +Magic Words are some phrases used in the wikitext. They are used for two things: +* Variables (like {{PAGENAME}}, {{SERVER}}, ...): part of wikitext, that looks + like templates but that don't accept any parameter. +* Parser functions (like {{fullurl:...}}, {{#special:...}}): behaves like + functions and accepts parameters. -The localized arrays keys are the internal IDs, and the values are an array, whose include their -case-sensitivity and their alias forms. The first form defined is used by the program, for example, -when moving a page and its old name should include #REDIRECT. +The localized arrays keys are the internal name, and the values are an array, +whose include their case-sensitivity and their alias forms. The first form +defined is used by the program, for example, when moving a page and its old name +should include #REDIRECT. -Adding magic words should be done using several hooks: -* "MagicWordMagicWords" should be used to add the internal name ('MAG_XXX') to $magicWords. -* "MagicWordwgVariableIDs" should be used to add the ID (MAG_XXX constant) to $wgVariableIDs. -* "LanguageGetMagic" should be used to add the different names of the magic word. Use both - the localized name and the English name. Get the language code by the parameter $langCode; +They can be added in several arrays: +* LanguageGetMagic hook, by adding a new key in $magicWords array. You can get + language code in the $lang parameter. Use both the localized name and the + English name. +* By adding a file to $wgExtensionMessagesFiles and defining there $magicWords. + This array is associative with the language code in the first dimension key + and then a "normal" array of magic words. +* Localized arrays (languages/messages/LanguageXX.php) include their different + names to be used by the users. -For example: +To add a new variable, you should use the "MagicWordwgVariableIDs" hook to add +the internal name to the $magicWords array. You'll need to define the value of +the variable with the "ParserGetVariableValueSwitch" hook. + +For example to add a new variable: -$wgHooks['MagicWordMagicWords'][] = 'wfAddCustomMagicWord'; $wgHooks['MagicWordwgVariableIDs'][] = 'wfAddCustomMagicWordID'; $wgHooks['LanguageGetMagic'][] = 'wfAddCustomMagicWordLang'; +$wgHooks['ParserGetVariableValueSwitch'][] = 'wfGetCustomMagicWordValue'; -function wfAddCustomMagicWord( &$magicWords ) { - $magicWords[] = 'MAG_CUSTOM'; +function wfAddCustomMagicWordID( &$magicWords ) { + $magicWords[] = 'mag_custom'; return true; } -function wfAddCustomMagicWordID( &$magicWords ) { - $magicWords[] = MAG_CUSTOM; +function wfAddCustomMagicWordLang( &$magicWords, $langCode ) { + switch ( $langCode ) { + case 'es': + $magicWords['mag_custom'] = array( 1, "ADUANERO", "CUSTOM" ); + break; + default: + $magicWords['mag_custom'] = array( 1, "CUSTOM" ); + } return true; } +function wfGetCustomMagicWordValue( &$parser, &$varCache, &$index, &$ret ){ + if( $index == 'mag_custom' ){ + $ret = $varCache['mag_custom'] = "Custom value"; + } + return true; +} + +And to add a new parser function: + +$wgHooks['LanguageGetMagic'][] = 'wfAddCustomMagicWordLang'; +$wgHooks['ParserFirstCallInit'][] = 'wfRegisterCustomMagicWord'; + function wfAddCustomMagicWordLang( &$magicWords, $langCode ) { switch ( $langCode ) { case 'es': - $magicWords[MAG_CUSTOM] = array( 0, "#aduanero", "#custom" ); + $magicWords['mag_custom'] = array( 0, "aduanero", "custom" ); break; default: - $magicWords[MAG_CUSTOM] = array( 0, "#custom" ); + $magicWords['mag_custom'] = array( 0, "custom" ); } return true; } + +function wfRegisterCustomMagicWord( &$parser ){ + $parser->setFunctionHook( 'mag_custom', 'wfGetCustomMagicWordValue' ); + return true; +} + +function wfGetCustomMagicWordValue( &$parser, $var1, $var2 ){ + return "custom: var1 is $var1, var2 is $var2"; +} + +Note: the 'ParserFirstCallInit' hook is only aviable since 1.12. To work with +an older version, you'll need to use an extension function. + +Online documentation (contains more informations): +Magic words: http://www.mediawiki.org/wiki/Manual:Magic_words +Variables: http://www.mediawiki.org/wiki/Manual:Variable +Parser functions: http://www.mediawiki.org/wiki/Manual:Parser_functions \ No newline at end of file diff --git a/docs/memcached.txt b/docs/memcached.txt index 3addd965..b31554cc 100644 --- a/docs/memcached.txt +++ b/docs/memcached.txt @@ -1,15 +1,19 @@ -memcached support for MediaWiki: - -From ca August 2003, MediaWiki has optional support for memcached, a -"high-performance, distributed memory object caching system". -For general information on it, see: http://www.danga.com/memcached/ +MediaWiki has optional support for memcached, a "high-performance, +distributed memory object caching system". For general information +on it, see: http://www.danga.com/memcached/ Memcached is likely more trouble than a small site will need, but for a larger site with heavy load, like Wikipedia, it should help lighten the load on the database servers by caching data and objects in memory. -== Requirements == +== Installation == + +Packages are available for Fedora, Debian, Ubuntu and probably other +Linux distributions. If you there's no package available for your +distribution, you can compile it from source. + +== Compilation == * PHP must be compiled with --enable-sockets @@ -35,18 +39,21 @@ server is appropriately firewalled, and that the port(s) used for memcached servers are not publicly accessible. Otherwise, anyone on the internet can put data into and read data from your cache. -An attacker familiar with MediaWiki internals could use this to give -themselves developer access and delete all data from the wiki's -database, as well as getting all users' password hashes and e-mail -addresses. +An attacker familiar with MediaWiki internals could use this to steal +passwords and email addresses, or to make themselves a sysop and +install malicious javascript on the site. There may be other types +of vulnerability, no audit has been done -- so be safe and keep it +behind a firewall. ********************* W A R N I N G ! ! ! ! ! *********************** == Setup == -If you want to start small, just run one memcached on your web -server: +If you installed memcached using a distro, the daemon should be started +automatically using /etc/init.d/memcached. - memcached -d -l 127.0.0.1 -p 11000 -m 64 +To start the daemon manually, use something like: + + memcached -d -l 127.0.0.1 -p 11211 -m 64 (to run in daemon mode, accessible only via loopback interface, on port 11000, using up to 64MB of memory) @@ -54,7 +61,7 @@ on port 11000, using up to 64MB of memory) In your LocalSettings.php file, set: $wgMainCacheType = CACHE_MEMCACHED; - $wgMemCachedServers = array( "127.0.0.1:11000" ); + $wgMemCachedServers = array( "127.0.0.1:11211" ); The wiki should then use memcached to cache various data. To use multiple servers (physically separate boxes or multiple caches @@ -70,61 +77,175 @@ usage evenly), make its entry a subarray: == PHP client for memcached == -As of this writing, MediaWiki includes version 1.0.10 of the PHP -memcached client by Ryan Gilfether . -You'll find some documentation for it in the 'php-memcached' -subdirectory under the present one. - -We intend to track updates, but if you want to check for the lastest -released version, see http://www.danga.com/memcached/apis.bml +MediaWiki uses a fork of Ryan T. Dean's pure-PHP memcached client. +The newer PECL module is not yet supported. -If you don't set $wgUseMemCached, we still create a MemCacheClient, +MediaWiki uses three object for object caching: +* $wgMemc, controlled by $wgMainCacheType +* $parserMemc, controlled by $wgParserCacheType +* $messageMemc, controlled by $wgMessageCacheType +If you set CACHE_NONE to one of the three control variable, (default +value for $wgMainCacheType), MediaWiki still create a MemCacheClient, but requests to it are no-ops and we always fall through to the database. If the cache daemon can't be contacted, it should also disable itself fairly smoothly. +By default, $wgMemc is used but when it is $parserMemc or $messageMemc +this is mentionned below. + == Keys used == -User: - key: $wgDBname:user:id:$sId - ex: wikidb:user:id:51 - stores: instance of class User - set in: User::loadFromSession() - cleared by: User::saveSettings(), UserTalkUpdate::doUpdate() - +(incomplete, out of date) + +Ajax Search: + key: $wgDBname:ajaxsearch:md5( $search ) + ex: wikidb:ajaxsearch:9565814d5d564fa898dd6111b94fae0b + stores: array with the result of research of a given text + cleared by: nothing + expiry: 30 minutes + +Date Formatter: + key: $wgDBname:dateformatter + ex: wikidb:dateformatter + stores: a single instance of the DateFormatter class + cleared by: nothing + expiry: one hour + +Difference Engine: + key: $wgDBname:diff:version:{MW_DIFF_VERSION}:oldid:$old:newid:$new + ex: wikidb:diff:version:1.11a:oldid:1:newid:2 + stores: body of a difference + cleared by: nothing + expiry: one week + +Interwiki: + key: $wgDBname:interwiki:$prefix + ex: wikidb:interwiki:w + stores: object from the interwiki table of the database + expiry: $wgInterwikiExpiry + cleared by: nothing + +Lag time of the databases: + key: $wgDBname:lag_times + ex: wikidb:lag_times + stores: array mapping the database id to its lag time + expriy: 5 secondes + cleared by: nothing + +Localisation: + key: $wgDBname:localisation:$lang + ex: wikidb:localisation:de + stores: array of localisation settings + set in: Language::loadLocalisation() + expiry: none + cleared by: Language::loadLocalisation() + +Message Cache: + stored in: $messageMemc + key: $wgDBname:messages, $wgDBname:messages-hash, $wgDBname:messages-status + ex: wikidb:messages, wikidb:messages-hash, wikidb:messages-status + stores: an array where the keys are DB keys and the values are messages + set in: wfMsg(), Article::editUpdates() both call wfLoadAllMessages() + expriy: $wgMsgCacheExpiry + cleared by: nothing + Newtalk: key: $wgDBname:newtalk:ip:$ip ex: wikidb:newtalk:ip:123.45.67.89 stores: integer, 0 or 1 set in: User::loadFromDatabase() cleared by: User::saveSettings() # ? - expiry set to 30 minutes - -LinkCache: - key: $wgDBname:lc:title:$title - ex: wikidb:lc:title:Wikipedia:Welcome,_Newcomers! - stores: cur_id of page, or 0 if page does not exist - set in: LinkCache::addLink() - cleared by: LinkCache::clearBadLink() - should be cleared on page deletion and rename -MediaWiki namespace: - key: $wgDBname:messages - ex: wikidb:messages - stores: an array where the keys are DB keys and the values are messages - set in: wfMsg(), Article::editUpdates() both call wfLoadAllMessages() + expiry: 30 minutes + +Parser Cache: + stored in: $parserMemc + controlled by: $wgEnableParserCache + key: $wgDBname:pcache:idhash:$pageid-$renderkey!$hash$edit + $pageid: id of the page + $renderkey: 1 if action=render, 0 otherwise + $hash: hash of user options, see User::getPageRenderingHash() + $edit: '!edit=0' if the user can't edit the page, '' otherwise + ex: wikidb:pcache:idhash:1-0!1!0!!en!2 + stores: ParserOutput object + modified by: Article::editUpdates() + expriy: $wgParserCacheExpireTime or one hour if it contains specific magic + words + +Ping limiter: + controlled by: $wgRateLimits + key: $wgDBname:limiter:action:$action:ip:$ip, + $wgDBname:limiter:action:$action:user:$id, + mediawiki:limiter:action:$action:ip:$ip and + mediawiki:limiter:action:$action:subnet:$sub + ex: wikidb:limiter:action:edit:ip:123.45.67.89, + wikidb:limiter:action:edit:user:1012 + mediawiki:limiter:action:edit:ip:123.45.67.89 and + mediawiki:limiter:action:$action:subnet:123.45.67 + stores: number of action made by user/ip/subnet cleared by: nothing + expiry: expiry set for the action and group in $wgRateLimits -Watchlist: - key: $wgDBname:watchlist:id:$userID - ex: wikidb:watchlist:id:4635 - stores: HTML string - cleared by: nothing, expiry time $wgWLCacheTimeout (1 hour) - note: emergency optimisation only - -IP blocks: - key: $wgDBname:ipblocks - ex: wikidb:ipblocks - stores: array of arrays, for the BlockCache class - cleared by: BlockCache:clear() + +Proxy Check: (deprecated) + key: $wgDBname:proxy:ip:$ip + ex: wikidb:proxy:ip:123.45.67.89 + stores: 1 if the ip is a proxy + cleared by: nothing + expiry: $wgProxyMemcExpiry + +Revision text: + key: $wgDBname:revisiontext:textid:$id + ex: wikidb:revisiontext:textid:1012 + stores: text of a revision + cleared by: nothing + expriry: $wgRevisionCacheExpiry + +Sessions: + controlled by: $wgSessionsInMemcached + key: $wgBDname:session:$id + ex: wikidb:session:38d7c5b8d3bfc51egf40c69bc40f8be3 + stores: $SESSION, useful when using a multi-sever wiki + expriy: one hour + cleared by: session_destroy() + +Sidebar: + stored in: $parserMemc + controlled by: $wgEnableSidebarCache + key: $wgDBname:sidebar + ex: wikidb:sidebar + stores: the html output of the sidebar + expriy: $wgSidebarCacheExpiry + cleared by: MessageCache::replace() + +Special:Allpages: + key: $wgDBname:allpages:ns:$ns + ex: wikidb:allpages:ns:0 + stores: array of pages in a namespace + expiry: one hour + cleared by: nothing + +Special:Recentchanges (feed): + stored in: $messageMemc + key: $wgDBname:rcfeed:$format:limit:$imit:minor:$hideminor and + rcfeed:$format:timestamp + ex: wikidb:rcfeed:rss:limit:50:minor:0 and rcfeed:rss:timestamp + stores: xml output of feed + expiry: one day + clear by: calling Special:Recentchanges?action=purge + +Statistics: + controlled by: $wgStatsMethod + key: $wgDBname:stats:$key + ex: wikibd:stats:request_with_session + stores: counter for statistics (see maintenance/stats.php script) + expiry: none (?) + cleared by: maintenance/clear_stats.php script + +User: + key: $wgDBname:user:id:$sId + ex: wikidb:user:id:51 + stores: instance of class User + set in: User::saveToCache() + cleared by: User::saveSettings(), User::clearSharedCache() -... more to come ... \ No newline at end of file +... more to come ... diff --git a/docs/scripts.txt b/docs/scripts.txt new file mode 100644 index 00000000..f8228a46 --- /dev/null +++ b/docs/scripts.txt @@ -0,0 +1,63 @@ +scripts.txt + +MediaWiki primary scripts are in the root directory of the software. Users +should only use these scripts to access the wiki. There are also some .php that +aren't primary scripts but helper files and won't work if they are accessed +directly by the web. + +Primary scripts: + + index.php + Main access point. It handles the most of requests. + See http://www.mediawiki.org/wiki/Manual:Index.php + + api.php + Script to provide an API for bots to fetch content and informations about + the site and also modify it. See http://www.mediawiki.org/wiki/API + for more informations. + + img_auth.php + Script that only serve images to logged in users. To configure the wiki + to use that script, see http://www.mediawiki.org/wiki/Manual:Image_Authorisation. + + opensearch_desc.php + Returns a OpenSearch description document (see http://www.opensearch.org/) + that points to the search engines of the wiki. + + profileinfo.php + Allow users to see the profiling information that are stored in the + database. + + To save the profiling information in the database (required to use this + script), you have to modify StartProfiler.php to use the Profiler class and + not the stub profiler which is enabled by default. + You will also need to set $wgProfileToDatabase to true in LocalSettings.php + to force the profiler to save the informations in the database and apply the + maintenance/archives/patch-profiling.sql patch to the database. + + To enable the profileinfo.php itself, you'll need to create the + AdminSettings.php file (see AdminSettings.sample for more information) and + set $wgEnableProfileInfo to true in that file. See also + http://www.mediawiki.org/wiki/How_to_debug#Profiling. + + redirect.php + Script that only redirect to the article passed in the wpDropdown parameter + of the request. Used by the nostalgia skin to access special pages with the + dropdown box at the top of the page. + + thumb.php + Script used to resize images if it is configured to be done when the web + browser requests the image and not when generating the page. This script can + be used as a 404 handler to generate image thumbs when they don't exist. + + trackback.php + Allow to add a new trackback to the database. This script returns XML + and require a POST request to work, thus it should only be accessed by some + specific programs and won't work with normal web browsers. + +There is also a file with a .php5 extension for each script. They can be used if +the web server needs a .php5 to run the file with the PHP 5 engine and runs .php +scripts with PHP 4. To use these files, you have to modify $wgScriptExtension to +'.php5' is LocalSettings.php but it is already done by the config script if you +used the config/index.php5 script. + diff --git a/docs/skin.txt b/docs/skin.txt index 82a5b72e..524a0397 100644 --- a/docs/skin.txt +++ b/docs/skin.txt @@ -1,48 +1,84 @@ - skin.txt -This document describes the overall architecture of MediaWiki's HTML rendering -code as well as some history about the skin system. It is placed here rather -than in comments in the code itself to help reduce the code size. +MediaWiki's default skin is called Monobook, after the black-and-white photo of +a book, in the page background. This skin has been the default since MediaWiki +1.3 (2004). It is used on Wikipedia, and is popular on other sites. + +There are three legacy skins which were introduced before MediaWiki 1.3: + +* Standard (a.k.a. Classic): The old default skin written by Lee Crocker +during the phase 3 rewrite, in 2002. + +* Nostalgia: A skin which looks like Wikipedia did in its first year (2001). +This skin is now used for the old Wikipedia snapshot at +http://nostalgia.wikipedia.org/ + +* Cologne Blue: A nicer-looking alternative to Standard. + + +And there are four Monobook-derived skins which have been introduced since 1.3: + +* MySkin: Monobook without the CSS. The idea is that you customise it using user +or site CSS (see below) + +* Chick: A lightweight Monobook skin with no sidebar, the sidebar links are +given at the bottom of the page instead, as in the unstyled MySkin. + +* Simple: A lightweight skin with a simple white-background sidebar and no +top bar. + +* Modern: An attractive blue/grey theme with sidebar and top bar. + + +== Custom CSS/JS == + +It is possible to customise the site CSS and JavaScript without editing any +source files. This is done by editing some pages on the wiki: + +* [[MediaWiki:Common.css]] -- for skin-independent CSS +* [[MediaWiki:Monobook.css]], [[MediaWiki:Simple.css]], etc. -- for +skin-dependent CSS +* [[MediaWiki:Common.js]], [[MediaWiki:Monobook.js]], etc. -- for custom +site JavaScript + +These can also be customised on a per-user basis, by editing +[[User:/monobook.css]], [[User:/monobook.js]], etc. + +This feature has led to a wide variety of "user styles" becoming available, +which change the appearance of Monobook or MySkin: + +http://meta.wikimedia.org/wiki/Gallery_of_user_styles -== Version 1.4 == +If you want a different look for your wiki, that gallery is a good place to start. -MediaWiki still use the PHPTal skin system introduced in version 1.3 but some -changes have been made to the file organisation. +== Drop-in custom skins == -PHP class and PHPTal templates have been moved to /skins/ (respectivly from -/includes/ and /templates/). This way skin designer and end user just stick to -one directory. +If you put a file in MediaWiki's skins directory, ending in .php, the name of +the file will automatically be added as a skin name, and the file will be +expected to contain a class called Skin with the skin class. You can then +make that skin the default by adding to LocalSettings.php: -Two samples are provided to start with, one for PHPTal use (SkinPHPTal.sample) -and one without (Skin.sample). +$wgDefaultSkin = ''; +You can also disable dropped-in or core skins using: -== Version 1.3 == +$wgSkipSkins[] = ''; -The following might help a bit though. +This technique is used by the more ambitious MediaWiki site operators, to +create complex custom skins for their wikis. It should be preferred over +editing the core Monobook skin directly. -Firstly, there's Skin.php; this file will check various settings, and it -contains a base class from which new skins can be derived. +See http://www.mediawiki.org/wiki/Manual:Skinning for more information. -Before version 1.3, each skin had its own PHP file (with a sub-class to Skin) -to generate the output. The files are: - * SkinCologneBlue.php - * SkinNostalgia.php - * SkinStandard.php - * SkinWikimediaWiki.php -If you want to change those skins, you have to edit these PHP files. - -Since 1.3 a new special skin file is available: SkinPHPTal.php. It makes use of -the PHPTal template engine and allows you to separate code and layout of the -pages. The default 1.3 skin is MonoBook and it uses the SkinPHPTAL class. +== Extension skins == -To change the layout, just edit the PHPTal template (templates/xhtml_slim.pt) -as well as the stylesheets (stylesheets/monobook/*). +It is now possible (since MediaWiki 1.12) to write a skin as a standard +MediaWiki extension, enabled via LocalSettings.php. This is done by adding +it to $wgValidSkinNames, for example: +$wgValidSkinNames['mycoolskin'] = 'My cool skin'; -== pre 1.3 version == +and then registering a class in $wgAutoloadClasses called SkinMycoolskin, which +derives from Skin. This technique is apparently not yet used (as of 2008) +outside the DumpHTML extension. -Unfortunately there isn't any documentation, and the code's in a bit of a mess -right now during the transition from the old skin code to the new template-based -skin code in 1.3. diff --git a/docs/title.txt b/docs/title.txt index fd449c54..d2d91c9c 100644 --- a/docs/title.txt +++ b/docs/title.txt @@ -1,76 +1,67 @@ title.txt -The MediaWiki software's "Title" class represents article -titles, which are used for many purposes: as the human-readable -text title of the article, in the URL used to access the article, -the wikitext link to the article, the key into the article -database, and so on. The class in instantiated from one of -these forms and can be queried for the others, and for other -attributes of the title. This is intended to be an -immutable "value" class, so there are no mutator functions. +The MediaWiki software's "Title" class represents article titles, which are used +for many purposes: as the human-readable text title of the article, in the URL +used to access the article, the wikitext link to the article, the key into the +article database, and so on. The class in instantiated from one of these forms +and can be queried for the others, and for other 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 Title::newFromURL(), Title::newFromDBKey(), -or Title::newFromText(). Once instantiated, the -other non-static accessor methods can be used, such as -getText(), getDBKey(), getNamespace(), etc. +To get a new instance, call Title::newFromText(). Once instantiated, the +non-static accessor methods can be used, such as getText(), getDBKey(), +getNamespace(), etc. Note that Title::newFromText() may return false if the text +is illegal according to the rules below. -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 -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 -with a ":". A prefix is only recognized if it is one of those -specifically allowed by the software. For example, "de:name" -is a link to the article "name" in the German Wikipedia, because -"de" is recognized as one of the allowable interwikis. The -title "talk:name" is a link to the article "name" in the "talk" -namespace of the current wiki, because "talk" is a recognized -namespace. Both may be present, and if so, the interwiki must -come first, for example, "m:talk:name". If a title begins with -a colon as its first character, no prefixes are scanned for, -and the colon is just removed. Note that because of these -rules, it is possible to have articles with colons in their -names. "E. Coli 0157:H7" is a valid title, as is "2001: A Space -Odyssey", because "E. Coli 0157" and "2001" are not valid -interwikis or namespaces. +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 +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 with a ":". A prefix is only recognized if it is +one of those specifically allowed by the software. For example, "de:name" is a +link to the article "name" in the German Wikipedia, because "de" is recognized +as one of the allowable interwikis. The title "talk:name" is a link to the +article "name" in the "talk" namespace of the current wiki, because "talk" is a +recognized namespace. Both may be present, and if so, the interwiki must +come first, for example, "m:talk:name". If a title begins with a colon as its +first character, no prefixes are scanned for, and the colon is just removed. +Note that because of these rules, it is possible to have articles with colons in +their names. "E. Coli 0157:H7" is a valid title, as is "2001: A Space Odyssey", +because "E. Coli 0157" and "2001" are not valid interwikis or namespaces. -It is not possible to have an article whose bare name includes -a namespace or interwiki prefix. +It is not possible to have an article whose bare name includes a namespace or +interwiki prefix. -An initial colon in a title listed in wiki text may however -suppress special handling for interlanguage links, image links, -and category links. +An initial colon in a title listed in wiki text may however suppress special +handling for interlanguage links, image links, and category links. It is also +used to indicate the main namespace in template inclusions. -Character mapping rules: Once prefixes have been stripped, the -rest of the title processed this way: spaces and underscores are -treated as equivalent and each is converted to the other in the -appropriate context (underscore in URL and database keys, spaces -in plain text). "Extended" characters in the 0x80..0xFF range -are allowed in all places, and are valid characters. They are -encoded in URLs. Other characters may be ASCII letters, digits, -hyphen, comma, period, apostrophe, parentheses, and colon. No -other ASCII characters are allowed, and will be deleted if found -(they will probably cause a browser to misinterpret the URL). -Extended characters are _not_ urlencoded when used as text or -database keys. +Once prefixes have been stripped, the rest of the title processed this way: -Character encoding rules: TODO +* Spaces and underscores are treated as equivalent and each is converted to the + other in the appropriate context (underscore in URL and database keys, spaces + in plain text). +* Multiple consecutive spaces are converted to a single space. +* Leading or trailing space is removed. +* If $wgCapitalLinks is enabled (the default), the first letter is capitalised, + using the capitalisation function of the content language object. +* The unicode characters LRM (U+200E) and RLM (U+200F) are silently stripped. +* Invalid UTF-8 sequences or instances of the replacement character (U+FFFD) are + considered illegal. +* A percent sign followed by two hexadecimal characters is illegal +* Anything that looks like an XML/HTML character reference is illegal +* Any character not matched by the $wgLegalTitleChars regex is illegal +* Zero-length titles (after whitespace stripping) are illegal -Canonical forms: the canonical form of a title will always be -returned by the object. In this form, the first (and only the -first) character of the namespace and title will be uppercased; -the rest of the namespace will be lowercased, while the title -will be left as is. The text form will use spaces, the URL and -DBkey forms will use underscores. Interwiki prefixes are all -lowercase. The namespace will use underscores when returned -alone; it will use spaces only when attached to the text title. +All titles except special pages must be less than 255 bytes when encoded with +UTF-8, because that is the size of the database field. Special page titles may +be up to 512 bytes. -getArticleID() needs some explanation: for "internal" articles, -it should return the "page_id" field if the article exists, else -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. +Note that Unicode Normal Form C (NFC) is enforced by MediaWiki's user interface +input functions, and so titles will typically be in this form. + +getArticleID() needs some explanation: for "internal" articles, it should return +the "page_id" field if the article exists, else 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. See linkcache.txt. -- cgit v1.2.2