docs/design.txt

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