docs/design.txt

   1 This is a brief overview of the new design.
   2
   3 More thorough and up-to-date information is available on the documentation
   4 wiki at http://www.mediawiki.org/
   5
   6 Primary source files/objects:
   7
   8   index.php
   9     Main script. It creates the necessary global objects and parses
  10     the URL to determine what to do, which it then generally passes
  11     off to somebody else (depending on the action to be taken).
  12
  13     All of the functions to which it might delegate generally do
  14     their job by sending content to the $wgOut object. After returning,
  15     the script flushes that out by calling $wgOut->output(). If there
  16     are any changes that need to be made to the database that can be
  17     deferred until after page display, those happen at the end.
  18
  19     Note that the order in the includes is touchy; Language uses
  20     some global functions, etc. Likewise with the creation of the
  21     global variables. Don't move them around without some forethought.
  22
  23   User
  24     Encapsulates the state of the user viewing/using the site.
  25     Can be queried for things like the user's settings, name, etc.
  26     Handles the details of getting and saving to the "user" table
  27     of the database, and dealing with sessions and cookies.
  28     More details in USER.TXT.
  29
  30   OutputPage
  31     Encapsulates the entire HTML page that will be sent in
  32     response to any server request. It is used by calling its
  33     functions to add text, headers, etc., in any order, and then
  34     calling output() to send it all. It could be easily changed
  35     to send incrementally if that becomes useful, but I prefer
  36     the flexibility. This should also do the output encoding.
  37     The system allocates a global one in $wgOut.
  38
  39   Title
  40     Represents the title of an article, and does all the work
  41     of translating among various forms such as plain text, URL,
  42     database key, etc. For convenience, and for historical
  43     reasons, it also represents a few features of articles that
  44     don't involve their text, such as access rights.
  45
  46   Article
  47     Encapsulates access to the "page" table of the database. The
  48     object represents a an article, and maintains state such as
  49     text (in Wikitext format), flags, etc.
  50
  51   Revision
  52     Encapsulates individual page revision data and access to the
  53     revision/text/blobs storage system. Higher-level code should
  54     never touch text storage directly; this class mediates it.
  55
  56   Skin
  57     Encapsulates a "look and feel" for the wiki. All of the
  58     functions that render HTML, and make choices about how to
  59     render it, are here, and are called from various other
  60     places when needed (most notably, OutputPage::addWikiText()).
  61     The StandardSkin object is a complete implementation, and is
  62     meant to be subclassed with other skins that may override
  63     some of its functions. The User object contains a reference
  64     to a skin (according to that user's preference), and so
  65     rather than having a global skin object we just rely on the
  66     global User and get the skin with $wgUser->getSkin().
  67
  68   Language
  69     Represents the language used for incidental text, and also
  70     has some character encoding functions and other locale stuff.
  71         The current user interface language is instantiated as $wgLang,
  72         and the local content language as $wgContLang; be sure to use
  73         the *correct* language object depending upon the circumstances.
  74
  75   LinkCache
  76     Keeps information on existence of articles. See LINKCACHE.TXT.
  77
  78 Naming/coding conventions:
  79
  80   These are meant to be descriptive, not dictatorial; I won't
  81   presume to tell you how to program, I'm just describing the
  82   methods I chose to use for myself. If you do choose to
  83   follow these guidelines, it will probably be easier for you
  84   to collaborate with others on the project, but if you want
  85   to contribute without bothering, by all means do so (and don't
  86   be surprised if I reformat your code).
  87
  88   - I have the code indented with tabs to save file size and
  89     so that users can set their tab stops to any depth they like.
  90     I use 4-space tab stops, which work well. I also use K&R brace
  91     matching style. I know that's a religious issue for some,
  92     so if you want to use a style that puts opening braces on the
  93     next line, that's OK too, but please don't use a style where
  94     closing braces don't align with either the opening brace on
  95     its own line or the statement that opened the block--that's
  96     confusing as hell.
  97
  98   - Certain functions and class members are marked with
  99         /* private */, rather than being marked as such. This is a
 100         hold-over from PHP 4, which didn't support proper visibilities.
 101         You should not access things marked in this manner outside the
 102         class/inheritance line as this code is subjected to be updated
 103         in a manner that enforces this at some time in the near future,
 104         and things will break. New code should use the standard method of
 105         setting visibilities as normal.
 106
 107   - Member variables are generally "mXxx" to distinguish them.
 108     This should make it easier to spot errors of forgetting the
 109     required "$this->", which PHP will happily accept by creating
 110     a new local variable rather than complaining.
 111
 112   - Globals are particularly evil in PHP; it sets a lot of them
 113     automatically from cookies, query strings, and such, leading to
 114     namespace conflicts; when a variable name is used in a function,
 115     it is silently declared as a new local masking the global, so
 116     you'll get weird error because you forgot the global declaration;
 117     lack of static class member variables means you have to use
 118     globals for them, etc. Evil, evil.
 119
 120     I think I've managed to pare down the number of globals we use
 121     to a scant few dozen or so, and I've prefixed them all with "wg"
 122     so you can spot errors better (odds are, if you see a "wg"
 123     variable being used in a function that doesn't declare it global,
 124     that's probably an error).
 125
 126     Other conventions: Top-level functions are wfFuncname(), names
 127     of session variables are wsName, cookies wcName, and form field
 128     values wpName ("p" for "POST").