[May 31st 2007]
-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 importants classes in MediaWiki.
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:
+For end user / administrators, most of the documentation is located online at:
http://www.mediawiki.org/wiki/Help:Contents
-
+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").
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 ) );
$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.
OutputPage object for HTTP response.
$wgUser
- User object for the user associated with the current
- request.
+ User object for the user associated with the current request.
$wgLang
Language object selected by user preferences.
$wgContLang
- Language object associated with the wiki being
- viewed.
+ Language object associated with the wiki being viewed.
$wgParser
- Parser object. Parser extensions register their
- hooks here.
+ Parser object. Parser extensions register their hooks here.
$wgRequest
WebRequest object, to get request data
$wgMessageCache
Message cache, to manage interface messages
-
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.
--- /dev/null
+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 to 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.
+
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 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.
+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. It is also used to indicate the main
-namespace in template inclusions.
+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.
-Once prefixes have been stripped, the rest of the title processed
-this way:
+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).
+* 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.
+* 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
-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.
+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.
-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.
+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.
+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.
dépôts / lhc / web / wiklou.git / commitdiff