summaryrefslogtreecommitdiff
path: root/docs/design.txt
blob: 1a35d5b0ddfca385e26d3812c8e19b6e3484f08e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
This is a brief overview of the new design.

More thorough and up-to-date information is available on the documentation
wiki at http://www.mediawiki.org/

Primary source files/objects:

  index.php
    Main script. It creates the necessary global objects and parses
    the URL to determine what to do, which it then generally passes
    off to somebody else (depending on the action to be taken).

    All of the functions to which it might delegate generally do
    their job by sending content to the $wgOut object. After returning,
    the script flushes that out by calling $wgOut->output(). If there
    are any changes that need to be made to the database that can be
    deferred until after page display, those happen at the end.

    Note that the order in the includes is touchy; Language uses
    some global functions, etc. Likewise with the creation of the
    global variables. Don't move them around without some forethought.

  User
    Encapsulates the state of the user viewing/using the site.
    Can be queried for things like the user's settings, name, etc.
    Handles the details of getting and saving to the "user" table
    of the database, and dealing with sessions and cookies.
    More details in USER.TXT.

  OutputPage
    Encapsulates the entire HTML page that will be sent in
    response to any server request. It is used by calling its
    functions to add text, headers, etc., in any order, and then
    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.

  Title
    Represents the title of an article, and does all the work
    of translating among various forms such as plain text, URL,
    database key, etc. For convenience, and for historical
    reasons, it also represents a few features of articles that
    don't involve their text, such as access rights.

  Article
    Encapsulates access to the "page" table of the database. The
    object represents a an article, and maintains state such as
    text (in Wikitext format), flags, etc.

  Revision
    Encapsulates individual page revision data and access to the
    revision/text/blobs storage system. Higher-level code should
    never touch text storage directly; this class mediates it.

  Skin
    Encapsulates a "look and feel" for the wiki. All of the
    functions that render HTML, and make choices about how to
    render it, are here, and are called from various other
    places when needed (most notably, OutputPage::addWikiText()).
    The StandardSkin object is a complete implementation, and is
    meant to be subclassed with other skins that may override
    some of its functions. The User object contains a reference
    to a skin (according to that user's preference), and so
    rather than having a global skin object we just rely on the
    global User and get the skin with $wgUser->getSkin().

  Language
    Represents the language used for incidental text, and also
    has some character encoding functions and other locale stuff.
	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.

Naming/coding conventions:

  These are meant to be descriptive, not dictatorial; I won't
  presume to tell you how to program, I'm just describing the
  methods I chose to use for myself. If you do choose to
  follow these guidelines, it will probably be easier for you
  to collaborate with others on the project, but if you want
  to contribute without bothering, by all means do so (and don't
  be surprised if I reformat your code).

  - I have the code indented with tabs to save file size and
    so that users can set their tab stops to any depth they like.
    I use 4-space tab stops, which work well. I also use K&R brace
    matching style. I know that's a religious issue for some,
    so if you want to use a style that puts opening braces on the
    next line, that's OK too, but please don't use a style where
    closing braces don't align with either the opening brace on
    its own line or the statement that opened the block--that's
    confusing as hell.

  - 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
    required "$this->", which PHP will happily accept by creating
    a new local variable rather than complaining.

  - Globals are particularly evil in PHP; it sets a lot of them
    automatically from cookies, query strings, and such, leading to
    namespace conflicts; when a variable name is used in a function,
    it is silently declared as a new local masking the global, so
    you'll get weird error because you forgot the global declaration;
    lack of static class member variables means you have to use
    globals for them, etc. Evil, evil.

    I think I've managed to pare down the number of globals we use
    to a scant few dozen or so, and I've prefixed them all with "wg"
    so you can spot errors better (odds are, if you see a "wg"
    variable being used in a function that doesn't declare it global,
    that's probably an error).

    Other conventions: Top-level functions are wfFuncname(), names
    of session variables are wsName, cookies wcName, and form field
    values wpName ("p" for "POST").