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