[Summary view] [Print] [Text view]

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