← Back to branch summary

~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to www/php/phpBB3/docs/auth_api.html

  • Committer: William Grant
  • Date: 2009-02-23 23:47:02 UTC
  • mfrom: (1099.1.211 new-dispatch)
  • Revision ID: grantw@unimelb.edu.au-20090223234702-db4b1llly46ignwo
Merge from lp:~ivle-dev/ivle/new-dispatch.

Pretty much everything changes. Reread the setup docs. Backup your databases.
Every file is now in a different installed location, the configuration system
is rewritten, the dispatch system is rewritten, URLs are different, the
database is different, worksheets and exercises are no longer on the
filesystem, we use a templating engine, jail service protocols are rewritten,
we don't repeat ourselves, we have authorization rewritten, phpBB is gone,
and probably lots of other things that I cannot remember.

This is certainly the biggest commit I have ever made, and hopefully
the largest I ever will.

Show diffs side-by-side

added added

removed removed

Lines of Context:
www/php/phpBB3/docs/auth_api.html
1
 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2
 
<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en" xml:lang="en">
3
 
<head>
4
 
 
5
 
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
6
 
<meta http-equiv="content-style-type" content="text/css" />
7
 
<meta http-equiv="content-language" content="en" />
8
 
<meta http-equiv="imagetoolbar" content="no" />
9
 
<meta name="resource-type" content="document" />
10
 
<meta name="distribution" content="global" />
11
 
<meta name="copyright" content="2007 phpBB Group" />
12
 
<meta name="keywords" content="" />
13
 
<meta name="description" content="This is an explanation of how to use the phpBB auth/acl API" />
14
 
<title>phpBB3 &bull; Auth API</title>
15
 
 
16
 
<link href="stylesheet.css" rel="stylesheet" type="text/css" media="screen, projection" />
17
 
 
18
 
</head>
19
 
 
20
 
<body id="phpbb" class="section-docs">
21
 
 
22
 
<div id="wrap">
23
 
        <a id="top" name="top" accesskey="t"></a>
24
 
        <div id="page-header">
25
 
                <div class="headerbar">
26
 
                        <div class="inner"><span class="corners-top"><span></span></span>
27
 
 
28
 
                        <div id="doc-description">
29
 
                                <a href="../index.php" id="logo"><img src="site_logo.gif" alt="" /></a>
30
 
                                <h1>Auth API</h1>
31
 
                                <p>This is an explanation of how to use the phpBB auth/acl API</p>
32
 
                                <p style="display: none;"><a href="#start_here">Skip</a></p>
33
 
                        </div>
34
 
 
35
 
                        <span class="corners-bottom"><span></span></span></div>
36
 
                </div>
37
 
        </div>
38
 
 
39
 
        <a name="start_here"></a>
40
 
 
41
 
        <div id="page-body">
42
 
 
43
 
<!-- BEGIN DOCUMENT -->
44
 
 
45
 
        <p>This is an explanation of how to use the phpBB auth/acl API.</p>
46
 
 
47
 
        <h1>Auth API</h1>
48
 
 
49
 
        <div class="paragraph menu">
50
 
                <div class="inner"><span class="corners-top"><span></span></span>
51
 
 
52
 
                <div class="content">
53
 
 
54
 
<ol>
55
 
        <li><a href="#intro">Introduction</a></li>
56
 
        <li><a href="#methods">Methods</a>
57
 
        <ol style="list-style-type: lower-roman;">
58
 
                <li><a href="#acl">acl</a></li>
59
 
                <li><a href="#acl_get">acl_get</a></li>
60
 
                <li><a href="#acl_gets">acl_gets</a></li>
61
 
                <li><a href="#acl_getf">acl_getf</a></li>
62
 
                <li><a href="#acl_getf_global">acl_getf_global</a></li>
63
 
                <li><a href="#acl_cache">acl_cache</a></li>
64
 
        </ol>
65
 
        </li>
66
 
        <li><a href="#admin_related">Admin related functions</a></li>
67
 
        <li><a href="#disclaimer">Copyright and disclaimer</a></li>
68
 
</ol>
69
 
 
70
 
                </div>
71
 
 
72
 
                <span class="corners-bottom"><span></span></span></div>
73
 
        </div>
74
 
 
75
 
        <hr />
76
 
 
77
 
<a name="intro"></a><h2>1. Introduction</h2>
78
 
 
79
 
        <div class="paragraph">
80
 
                <div class="inner"><span class="corners-top"><span></span></span>
81
 
 
82
 
                <div class="content">
83
 
 
84
 
        <h4>What is it?</h4>
85
 
 
86
 
        <p>The <code>auth</code> class contains methods related to authorisation users to access various board functions, e.g. posting, viewing, replying, logging in (and out), etc. If you need to check whether a user can carry out a task or handle user login/logouts this class is required.</p>
87
 
 
88
 
        <h4>Initialisation</h4>
89
 
 
90
 
        <p>To use any methods contained with the <code>auth</code> class it first needs to be instantiated. This is best achieved early in the execution of the script in the following manner:</p>
91
 
 
92
 
        <div class="codebox"><pre>
93
 
$auth = new auth();
94
 
        </pre></div>
95
 
 
96
 
        <p>Once an instance of the class has been created you are free to call the various methods it contains. Please note that should you wish to use the <code>auth_admin</code> methods you will need to instantiate this separately but in the same way.</p>
97
 
 
98
 
                </div>
99
 
 
100
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
101
 
 
102
 
                <span class="corners-bottom"><span></span></span></div>
103
 
        </div>
104
 
 
105
 
        <hr />
106
 
 
107
 
<a name="methods"></a><h2>2. Methods</h2>
108
 
 
109
 
        <div class="paragraph">
110
 
                <div class="inner"><span class="corners-top"><span></span></span>
111
 
 
112
 
                <div class="content">
113
 
 
114
 
        <p>Following are the methods you are able to use.</p>
115
 
 
116
 
        <a name="acl"></a><h3>2.i. acl</h3>
117
 
        
118
 
        <p>The <code>acl</code> method is the initialisation routine for all the acl functions. If you intend calling any acl method you must first call this. The method takes as its one and only required parameter an associative array containing user information as stored in the database. This array must contain at least the following information; user_id, user_permissions and user_type. It is called in the following way:</p>
119
 
 
120
 
        <div class="codebox"><pre>
121
 
$auth-&gt;acl(<code>userdata</code>);
122
 
        </pre></div>
123
 
 
124
 
        <p>Where userdata is the array containing the aforementioned data.</p>
125
 
 
126
 
        <a name="acl_get"></a><h3>2.ii. acl_get</h3>
127
 
 
128
 
        <p>This method is the primary way of determining what a user can and cannot do for a given option globally or in a given forum. The method should be called in the following way:</p>
129
 
 
130
 
        <div class="codebox"><pre>
131
 
$result = $auth-&gt;acl_get(<code>option</code>[, <code>forum</code>]);
132
 
        </pre></div>
133
 
 
134
 
        <p>Where option is a string representing the required option, e.g. 'f_list', 'm_edit', 'a_adduser', etc. By adding a ! in front of the option, e.g. '!f_list' the result of this method will be negated. The optional forum term is the integer forum_id.</p>
135
 
 
136
 
        <p>The method returns a positive integer when the user is allowed to carry out the option and a zero if denied or the other way around if the option is prefixed with an exclamation mark.</p>
137
 
 
138
 
        <p>If you specify a forum and there is also a global setting for the specified option then this method will return a positive integer if one of them evaluates to a positive integer. An example would be the m_approve option which can be set per forum but also globally. If a user has the global option he will automatically have m_approve in every forum.</p>
139
 
 
140
 
        <p>There are some special options or <em>flags</em> which are used as prefixes for other options, e.g. 'f_' or 'm_'. These flags will automatically be set to a positive integer if the user has one or more permissions with the given prefix. A local setting will result in the flag being set only locally (so it will require a forum id to retrieve). If a user has one or more global permissions with the prefix acl_get will return a positive integer regardless of the forum id.</p>
141
 
 
142
 
        <a name="acl_gets"></a><h3>2.iii. acl_gets</h3>
143
 
 
144
 
        <p>This method is funtionally similar to <code>acl_get</code> in that it returns information on whether a user can or cannot carry out a given task. The difference here is the ability to test several different options in one go. This may be useful for testing whether a user is a moderator or an admin in one call. Rather than having to call and check <code>acl_get</code> twice.</p>
145
 
 
146
 
        <p>The method should be called thus:</p>
147
 
 
148
 
        <div class="codebox"><pre>
149
 
$result = $auth-&gt;acl_gets(<code>option1</code>[, <code>option2</code>, ..., <code>optionN</code>, <code>forum</code>]);
150
 
        </pre></div>
151
 
 
152
 
        <p>As with the <code>acl_get</code> method the options are strings representing the required permissions to check. The forum again is an integer representing a given forum_id.</p>
153
 
 
154
 
        <p>The method will return a positive integer if <code>acl_get</code> for one of the options evaluates to a positive integer (combines permissions with OR).</p>
155
 
 
156
 
        <a name="acl_getf"></a><h3>2.iv. acl_getf</h3>
157
 
 
158
 
        <p>This method is used to find out in which forums a user is allowed to carry out an operation or to find out in which forums he is not allowed to carry out an operation. The method should be called in the following way:</p>
159
 
 
160
 
        <div class="codebox"><pre>
161
 
$result = $auth-&gt;acl_getf(<code>option</code>[, <code>clean</code>]);
162
 
        </pre></div>
163
 
 
164
 
        <p>Just like in the <code>acl_get</code> method the option is a string specifying the permission which has to be checked (negation using ! is allowed). The second parameter is a boolean. If it is set to false this method returns all forums with either zero or a positive integer. If it is set to true only those forums with a positive integer as the result will be returned.</p>
165
 
 
166
 
        <p>The method returns an associative array of the form:</p>
167
 
 
168
 
        <div class="codebox"><pre>
169
 
array(<em>forum_id1</em> =&gt; array(<em>option</em> =&gt; <em>integer</em>), <em>forum_id2</em> =&gt; ...)
170
 
        </pre></div>
171
 
 
172
 
        <p>Where option is the option passed to the method and integer is either zero or a positive integer and the same <code>acl_get(option, forum_id)</code> would return.</p>
173
 
 
174
 
        <a name="acl_getf_global"></a><h3>2.v. acl_getf_global</h3>
175
 
 
176
 
        <p>This method is used to find out whether a user has a permission in at least one forum or globally. This method is similar to checking whether <code>acl_getf(option, true)</code> returned one or more forums but it's faster. It should be called in the following way:</p>
177
 
 
178
 
        <div class="codebox"><pre>
179
 
$result = acl_getf_global(<code>option</code>)
180
 
        </pre></div>
181
 
 
182
 
        <p>As with the previous methods option is a string specifying the permission which has to be checked.</p>
183
 
 
184
 
        <p>This method returns either zero or a positive integer.</p>
185
 
 
186
 
        <a name="acl_cache"></a><h3>2.vi. acl_cache</h3>
187
 
 
188
 
        <p>This should be considered a private method and not be called externally. It handles the generation of the user_permissions data from the basic user and group authorisation data. When necessary this method is called automatically by <code>acl</code>.</p>
189
 
 
190
 
                </div>
191
 
 
192
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
193
 
 
194
 
                <span class="corners-bottom"><span></span></span></div>
195
 
        </div>
196
 
 
197
 
        <hr />
198
 
 
199
 
<a name="admin_related"></a><h2>3. Admin related functions</h2>
200
 
 
201
 
        <div class="paragraph">
202
 
                <div class="inner"><span class="corners-top"><span></span></span>
203
 
 
204
 
                <div class="content">
205
 
 
206
 
        <p>A number of additional methods are available related to <code>auth</code>. These handle more basic functions such as adding user and group permissions, new options and clearing the user cache. These methods are contained within a separate class, <code>auth_admin</code>. This can be found in <code>includes/acp/auth.php</code>.</p>
207
 
 
208
 
        <p>To use any methods this class contains it first needs to be instantiated separately from <code>auth</code>. This is achieved in the same way as <code>auth</code>:</p>
209
 
 
210
 
        <div class="codebox"><pre>
211
 
$auth_admin = new auth_admin();
212
 
        </pre></div>
213
 
 
214
 
        <p>This instance gives you access to both the methods of this specific class and that of <code>auth</code>.</p>
215
 
 
216
 
                </div>
217
 
 
218
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
219
 
 
220
 
                <span class="corners-bottom"><span></span></span></div>
221
 
        </div>
222
 
 
223
 
        <hr />
224
 
 
225
 
<a name="disclaimer"></a><h2>4. Copyright and disclaimer</h2>
226
 
 
227
 
        <div class="paragraph">
228
 
                <div class="inner"><span class="corners-top"><span></span></span>
229
 
 
230
 
                <div class="content">
231
 
 
232
 
        <p>This application is opensource software released under the <a href="http://opensource.org/licenses/gpl-license.php">GPL</a>. Please see source code and the docs directory for more details. This package and its contents are Copyright (c) 2000, 2002, 2005, 2007 <a href="http://www.phpbb.com/">phpBB Group</a>, All Rights Reserved.</p>
233
 
 
234
 
                </div>
235
 
 
236
 
                <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
237
 
 
238
 
                <span class="corners-bottom"><span></span></span></div>
239
 
        </div>
240
 
 
241
 
<!-- END DOCUMENT -->
242
 
 
243
 
        <div id="page-footer">
244
 
                <div class="version"> $Id: auth_api.html,v 1.8 2007/09/22 18:13:08 acydburn Exp $ </div>
245
 
        </div>
246
 
</div></div>
247
 
 
248
 
<div>
249
 
        <a id="bottom" name="bottom" accesskey="z"></a>
250
 
</div>
251
 
 
252
 
</body>
253
 
</html>