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. This class
  38     also handles converting wikitext format to HTML.
  39
  40   Title
  41     Represents the title of an article, and does all the work
  42     of translating among various forms such as plain text, URL,
  43     database key, etc. For convenience, and for historical
  44     reasons, it also represents a few features of articles that
  45     don't involve their text, such as access rights.
  46
  47   Article
  48     Encapsulates access to the "page" table of the database. The
  49     object represents a an article, and maintains state such as
  50     text (in Wikitext format), flags, etc.
  51
  52   Revision
  53     Encapsulates individual page revision data and access to the
  54     revision/text/blobs storage system. Higher-level code should
  55     never touch text storage directly; this class mediates it.
  56
  57   Skin
  58     Encapsulates a "look and feel" for the wiki. All of the
  59     functions that render HTML, and make choices about how to
  60     render it, are here, and are called from various other
  61     places when needed (most notably, OutputPage::addWikiText()).
  62     The StandardSkin object is a complete implementation, and is
  63     meant to be subclassed with other skins that may override
  64     some of its functions. The User object contains a reference
  65     to a skin (according to that user's preference), and so
  66     rather than having a global skin object we just rely on the
  67     global User and get the skin with $wgUser->getSkin().
  68
  69   Language
  70     Represents the language used for incidental text, and also
  71     has some character encoding functions and other locale stuff.
  72     A global one is allocated in $wgLang.
  73
  74   LinkCache
  75     Keeps information on existence of articles. See LINKCACHE.TXT.
  76
  77 Naming/coding conventions:
  78
  79   These are meant to be descriptive, not dictatorial; I won't
  80   presume to tell you how to program, I'm just describing the
  81   methods I chose to use for myself. If you do choose to
  82   follow these guidelines, it will probably be easier for you
  83   to collaborate with others on the project, but if you want
  84   to contribute without bothering, by all means do so (and don't
  85   be surprised if I reformat your code).
  86
  87   - I have the code indented with tabs to save file size and
  88     so that users can set their tab stops to any depth they like.
  89     I use 4-space tab stops, which work well. I also use K&R brace
  90     matching style. I know that's a religious issue for some,
  91     so if you want to use a style that puts opening braces on the
  92     next line, that's OK too, but please don't use a style where
  93     closing braces don't align with either the opening brace on
  94     its own line or the statement that opened the block--that's
  95     confusing as hell.
  96
  97   - PHP doesn't have "private" member variables of functions,
  98     so I've used the comment "/* private */" in some places to
  99     indicate my intent. Don't access things marked that way
 100     from outside the class def--use the accessor functions (or
 101     make your own if you need them). Yes, even some globals
 102     are marked private, because PHP is broken and doesn't
 103     allow static class variables.
 104
 105   - Member variables are generally "mXxx" to distinguish them.
 106     This should make it easier to spot errors of forgetting the
 107     required "$this->", which PHP will happily accept by creating
 108     a new local variable rather than complaining.
 109
 110   - Globals are particularly evil in PHP; it sets a lot of them
 111     automatically from cookies, query strings, and such, leading to
 112     namespace conflicts; when a variable name is used in a function,
 113     it is silently declared as a new local masking the global, so
 114     you'll get weird error because you forgot the global declaration;
 115     lack of static class member variables means you have to use
 116     globals for them, etc. Evil, evil.
 117
 118     I think I've managed to pare down the number of globals we use
 119     to a scant few dozen or so, and I've prefixed them all with "wg"
 120     so you can spot errors better (odds are, if you see a "wg"
 121     variable being used in a function that doesn't declare it global,
 122     that's probably an error).
 123
 124     Other conventions: Top-level functions are wfFuncname(), names
 125     of session variables are wsName, cookies wcName, and form field
 126     values wpName ("p" for "POST").
 127