Verzeichnisstruktur phpBB-3.1.0
- Veröffentlicht
- 27.10.2014
So funktioniert es
|
|
Auf das letzte Element klicken. Dies geht jeweils ein Schritt zurück |
Auf das Icon klicken, dies öffnet das Verzeichnis. Nochmal klicken schließt das Verzeichnis. |
|
|
(Beispiel Datei-Icons)
|
Auf das Icon klicken um den Quellcode anzuzeigen |
auth_api.html
001 <!DOCTYPE html>
002 <html dir="ltr" lang="en">
003 <head>
004 <meta charset="utf-8">
005 <meta name="keywords" content="" />
006 <meta name="description" content="This is an explanation of how to use the phpBB auth/acl API" />
007 <title>phpBB3 • Auth API</title>
008
009 <link href="stylesheet.css" rel="stylesheet" type="text/css" media="screen, projection" />
010
011 </head>
012
013 <body id="phpbb" class="section-docs">
014
015 <div id="wrap">
016 <a id="top" name="top" accesskey="t"></a>
017 <div id="page-header">
018 <div class="headerbar">
019 <div class="inner"><span class="corners-top"><span></span></span>
020
021 <div id="doc-description">
022 <a href="../index.php" id="logo"><img src="site_logo.gif" alt="" /></a>
023 <h1>Auth API</h1>
024 <p>This is an explanation of how to use the phpBB auth/acl API</p>
025 <p style="display: none;"><a href="#start_here">Skip</a></p>
026 </div>
027
028 <span class="corners-bottom"><span></span></span></div>
029 </div>
030 </div>
031
032 <a name="start_here"></a>
033
034 <div id="page-body">
035
036 <!-- BEGIN DOCUMENT -->
037
038 <p>This is an explanation of how to use the phpBB auth/acl API.</p>
039
040 <h1>Auth API</h1>
041
042 <div class="paragraph menu">
043 <div class="inner"><span class="corners-top"><span></span></span>
044
045 <div class="content">
046
047 <ol>
048 <li><a href="#intro">Introduction</a></li>
049 <li><a href="#methods">Methods</a>
050 <ol style="list-style-type: lower-roman;">
051 <li><a href="#acl">acl</a></li>
052 <li><a href="#acl_get">acl_get</a></li>
053 <li><a href="#acl_gets">acl_gets</a></li>
054 <li><a href="#acl_getf">acl_getf</a></li>
055 <li><a href="#acl_getf_global">acl_getf_global</a></li>
056 <li><a href="#acl_cache">acl_cache</a></li>
057 <li><a href="#acl_clear_prefetch">acl_clear_prefetch</a></li>
058 <li><a href="#acl_get_list">acl_get_list</a></li>
059 <li><a href="#misc">Miscellaneous</a></li>
060 </ol>
061 </li>
062 <li><a href="#admin_related">Admin related functions</a></li>
063 <li><a href="#disclaimer">Copyright and disclaimer</a></li>
064 </ol>
065
066 </div>
067
068 <span class="corners-bottom"><span></span></span></div>
069 </div>
070
071 <hr />
072
073 <a name="intro"></a><h2>1. Introduction</h2>
074
075 <div class="paragraph">
076 <div class="inner"><span class="corners-top"><span></span></span>
077
078 <div class="content">
079
080 <h4>What is it?</h4>
081
082 <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>
083
084 <h4>Initialisation</h4>
085
086 <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>
087
088 <div class="codebox"><pre>
089 $auth = new phpbb\auth\auth();
090 </pre></div>
091
092 <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>
093
094 </div>
095
096 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
097
098 <span class="corners-bottom"><span></span></span></div>
099 </div>
100
101 <hr />
102
103 <a name="methods"></a><h2>2. Methods</h2>
104
105 <div class="paragraph">
106 <div class="inner"><span class="corners-top"><span></span></span>
107
108 <div class="content">
109
110 <p>Following are the methods you are able to use.</p>
111
112 <a name="acl"></a><h3>2.i. acl</h3>
113
114 <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>
115
116 <div class="codebox"><pre>
117 $auth->acl(<code>userdata</code>);
118 </pre></div>
119
120 <p>Where userdata is the array containing the aforementioned data.</p>
121
122 <a name="acl_get"></a><h3>2.ii. acl_get</h3>
123
124 <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>
125
126 <div class="codebox"><pre>
127 $result = $auth->acl_get(<code>option</code>[, <code>forum</code>]);
128 </pre></div>
129
130 <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>
131
132 <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>
133
134 <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>
135
136 <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>
137
138 <a name="acl_gets"></a><h3>2.iii. acl_gets</h3>
139
140 <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>
141
142 <p>The method should be called thus:</p>
143
144 <div class="codebox"><pre>
145 $result = $auth->acl_gets(<code>option1</code>[, <code>option2</code>, ..., <code>optionN</code>, <code>forum</code>]);
146 </pre></div>
147
148 <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>
149
150 <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>
151
152 <a name="acl_getf"></a><h3>2.iv. acl_getf</h3>
153
154 <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>
155
156 <div class="codebox"><pre>
157 $result = $auth->acl_getf(<code>option</code>[, <code>clean</code>]);
158 </pre></div>
159
160 <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>
161
162 <p>The method returns an associative array of the form:</p>
163
164 <div class="codebox"><pre>
165 array(<em>forum_id1</em> => array(<em>option</em> => <em>integer</em>), <em>forum_id2</em> => ...)
166 </pre></div>
167
168 <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>
169
170 <a name="acl_getf_global"></a><h3>2.v. acl_getf_global</h3>
171
172 <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>
173
174 <div class="codebox"><pre>
175 $result = $auth->acl_getf_global(<code>option</code>)
176 </pre></div>
177
178 <p>As with the previous methods option is a string specifying the permission which has to be checked.</p>
179
180 <p>This method returns either zero or a positive integer.</p>
181
182 <a name="acl_cache"></a><h3>2.vi. acl_cache</h3>
183
184 <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>
185
186 <a name="acl_clear_prefetch"></a><h3>2.vii. acl_clear_prefetch</h3>
187
188 <p>This method clears the user_permissions column in the users table for the given user. If the user ID passed is zero, the permissions cache is cleared for all users. This method should be called whenever permissions are set.</p>
189
190 <div class="codebox"><pre>
191 // clear stored permissions for user 2
192 $user_id = 2;
193 $auth->acl_clear_prefetch($user_id);
194 </pre></div>
195
196 <p>This method returns null.</p>
197
198 <a name="acl_get_list"></a><h3>2.viii. acl_get_list</h3>
199
200 <p>This method returns an an array describing which users have permissions in given fora. The resultant array contains an entry for permission that every user has in every forum when no arguments are passed.</p>
201
202 <div class="codebox"><pre>
203 $user_id = array(2, 53);
204 $permissions = array('f_list', 'f_read');
205 $forum_id = array(1, 2, 3);
206 $result = $auth->acl_get_list($user_id, $permissions, $forum_id);
207 </pre></div>
208
209 <p>The parameters may be of the following legal types:</p>
210 <ul>
211 <li><strong>$user_id</strong>: <code>false</code>, int, array(int, int, int, ...)</li>
212 <li><strong>$permissions</strong>: <code>false</code>, string, array(string, string, ...)</li>
213 <li><strong>$forum_id</strong>: <code>false</code>, int, array(int, int, int, ...)</li>
214 </ul>
215
216 <a name="misc"></a><h3>2.ix. Miscellaneous</h3>
217
218 <p>There are other methods defined in the auth class which serve mostly as private methods, but are available for use if needed. Each of them is used to pull data directly from the database tables. They are:</p>
219 <ul>
220 <li><pre>function acl_group_raw_data($group_id = false, $opts = false, $forum_id = false)</pre></li>
221 <li><pre>function acl_user_raw_data($user_id = false, $opts = false, $forum_id = false)</pre></li>
222 <li><pre>function acl_raw_data_single_user($user_id)</pre></li>
223 <li><pre>function acl_raw_data($user_id = false, $opts = false, $forum_id = false)</pre></li>
224 <li><pre>function acl_role_data($user_type, $role_type, $ug_id = false, $forum_id = false)</pre></li>
225 </ul>
226
227 <p>Of these, <code>acl_raw_data</code> is the most general, but the others will be faster if you need a smaller amount of data.</p>
228
229 </div>
230
231 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
232
233 <span class="corners-bottom"><span></span></span></div>
234 </div>
235
236 <hr />
237
238 <a name="admin_related"></a><h2>3. Admin related functions</h2>
239
240 <div class="paragraph">
241 <div class="inner"><span class="corners-top"><span></span></span>
242
243 <div class="content">
244
245 <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>
246
247 <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>
248
249 <div class="codebox"><pre>
250 $auth_admin = new auth_admin();
251 </pre></div>
252
253 <p>This instance gives you access to both the methods of this specific class and that of <code>auth</code>.</p>
254
255 </div>
256
257 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
258
259 <span class="corners-bottom"><span></span></span></div>
260 </div>
261
262 <hr />
263
264 <a name="disclaimer"></a><h2>4. Copyright and disclaimer</h2>
265
266 <div class="paragraph">
267 <div class="inner"><span class="corners-top"><span></span></span>
268
269 <div class="content">
270
271 <p>phpBB is free software, released under the terms of the <a href="http://opensource.org/licenses/gpl-2.0.php">GNU General Public License, version 2 (GPL-2.0)</a>. Copyright © <a href="https://www.phpbb.com">phpBB Limited</a>. For full copyright and license information, please see the docs/CREDITS.txt file.</p>
272
273 </div>
274
275 <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
276
277 <span class="corners-bottom"><span></span></span></div>
278 </div>
279
280 <!-- END DOCUMENT -->
281
282 <div id="page-footer">
283 <div class="version"> </div>
284 </div>
285 </div></div>
286
287 <div>
288 <a id="bottom" name="bottom" accesskey="z"></a>
289 </div>
290
291 </body>
292 </html>
293