Verzeichnisstruktur phpBB-3.2.0


Veröffentlicht
06.01.2017

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.
Auf den Verzeichnisnamen klicken, dies zeigt nur das Verzeichnis mit Inhalt an

      (Beispiel Datei-Icons)

Auf das Icon klicken um den Quellcode anzuzeigen

auth_api.html

Zuletzt modifiziert: 09.10.2024, 12:51 - Dateigröße: 12.18 KiB


 001  <!DOCTYPE html>
 002  <html dir="ltr" lang="en">
 003  <head>
 004  <meta charset="utf-8">
 005  <meta http-equiv="X-UA-Compatible" content="IE=edge">
 006  <meta name="keywords" content="" />
 007  <meta name="description" content="This is an explanation of how to use the phpBB auth/acl API" />
 008  <title>phpBB3 &bull; Auth API</title>
 009   
 010  <link href="assets/css/stylesheet.css" rel="stylesheet" type="text/css" media="screen" />
 011   
 012  </head>
 013   
 014  <body id="phpbb" class="section-docs">
 015   
 016  <div id="wrap">
 017      <a id="top" name="top" accesskey="t"></a>
 018      <div id="page-header">
 019          <div class="headerbar">
 020              <div class="inner">
 021   
 022              <div id="doc-description">
 023                  <a href="../index.php" id="logo"><img src="assets/images/site_logo.gif" alt="" /></a>
 024                  <h1>Auth API</h1>
 025                  <p>This is an explanation of how to use the phpBB auth/acl API</p>
 026                  <p style="display: none;"><a href="#start_here">Skip</a></p>
 027              </div>
 028   
 029              </div>
 030          </div>
 031      </div>
 032   
 033      <a name="start_here"></a>
 034   
 035      <div id="page-body">
 036   
 037  <!-- BEGIN DOCUMENT -->
 038   
 039      <p class="paragraph main-description">This is an explanation of how to use the phpBB auth/acl API.</p>
 040   
 041      <h1>Auth API</h1>
 042   
 043      <div class="paragraph menu">
 044          <div class="inner">
 045   
 046          <div class="content">
 047   
 048  <ol>
 049      <li><a href="#intro">Introduction</a></li>
 050      <li><a href="#methods">Methods</a>
 051      <ol style="list-style-type: lower-roman;">
 052          <li><a href="#acl">acl</a></li>
 053          <li><a href="#acl_get">acl_get</a></li>
 054          <li><a href="#acl_gets">acl_gets</a></li>
 055          <li><a href="#acl_getf">acl_getf</a></li>
 056          <li><a href="#acl_getf_global">acl_getf_global</a></li>
 057          <li><a href="#acl_cache">acl_cache</a></li>
 058          <li><a href="#acl_clear_prefetch">acl_clear_prefetch</a></li>
 059          <li><a href="#acl_get_list">acl_get_list</a></li>
 060          <li><a href="#misc">Miscellaneous</a></li>
 061      </ol>
 062      </li>
 063      <li><a href="#admin_related">Admin related functions</a></li>
 064      <li><a href="#disclaimer">Copyright and disclaimer</a></li>
 065  </ol>
 066   
 067          </div>
 068   
 069          </div>
 070      </div>
 071   
 072      <hr />
 073   
 074  <a name="intro"></a><h2>1. Introduction</h2>
 075   
 076      <div class="paragraph">
 077          <div class="inner">
 078   
 079          <div class="content">
 080   
 081      <h4>What is it?</h4>
 082   
 083      <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>
 084   
 085      <h4>Initialisation</h4>
 086   
 087      <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>
 088   
 089      <div class="codebox"><pre>
 090  $auth = new phpbb\auth\auth();</pre>
 091      </div>
 092   
 093      <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>
 094   
 095          </div>
 096   
 097          <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
 098   
 099          </div>
 100      </div>
 101   
 102      <hr />
 103   
 104  <a name="methods"></a><h2>2. Methods</h2>
 105   
 106      <div class="paragraph">
 107          <div class="inner">
 108   
 109          <div class="content">
 110   
 111      <p>Following are the methods you are able to use.</p>
 112   
 113      <a name="acl"></a><h3>2.i. acl</h3>
 114   
 115      <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>
 116   
 117      <div class="codebox"><pre>
 118  $auth-&gt;acl(<code>userdata</code>);</pre>
 119      </div>
 120   
 121      <p>Where userdata is the array containing the aforementioned data.</p>
 122   
 123      <a name="acl_get"></a><h3>2.ii. acl_get</h3>
 124   
 125      <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>
 126   
 127      <div class="codebox"><pre>
 128  $result = $auth-&gt;acl_get(<code>option</code>[, <code>forum</code>]);</pre>
 129      </div>
 130   
 131      <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>
 132   
 133      <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>
 134   
 135      <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>
 136   
 137      <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>
 138   
 139      <a name="acl_gets"></a><h3>2.iii. acl_gets</h3>
 140   
 141      <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>
 142   
 143      <p>The method should be called thus:</p>
 144   
 145      <div class="codebox"><pre>
 146  $result = $auth-&gt;acl_gets(<code>option1</code>[, <code>option2</code>, ..., <code>optionN</code>, <code>forum</code>]);</pre>
 147      </div>
 148   
 149      <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>
 150   
 151      <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>
 152   
 153      <a name="acl_getf"></a><h3>2.iv. acl_getf</h3>
 154   
 155      <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>
 156   
 157      <div class="codebox"><pre>
 158  $result = $auth-&gt;acl_getf(<code>option</code>[, <code>clean</code>]);</pre>
 159      </div>
 160   
 161      <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>
 162   
 163      <p>The method returns an associative array of the form:</p>
 164   
 165      <div class="codebox"><pre>
 166  array(<em>forum_id1</em> =&gt; array(<em>option</em> =&gt; <em>integer</em>), <em>forum_id2</em> =&gt; ...)</pre>
 167      </div>
 168   
 169      <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>
 170   
 171      <a name="acl_getf_global"></a><h3>2.v. acl_getf_global</h3>
 172   
 173      <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>
 174   
 175      <div class="codebox"><pre>
 176  $result = $auth-&gt;acl_getf_global(<code>option</code>)</pre>
 177      </div>
 178   
 179      <p>As with the previous methods option is a string specifying the permission which has to be checked.</p>
 180   
 181      <p>This method returns either zero or a positive integer.</p>
 182   
 183      <a name="acl_cache"></a><h3>2.vi. acl_cache</h3>
 184   
 185      <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>
 186   
 187      <a name="acl_clear_prefetch"></a><h3>2.vii. acl_clear_prefetch</h3>
 188   
 189      <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>
 190   
 191      <div class="codebox"><pre>
 192  // clear stored permissions for user 2
 193  $user_id = 2;
 194  $auth->acl_clear_prefetch($user_id);
 195  </pre></div>
 196   
 197      <p>This method returns null.</p>
 198   
 199      <a name="acl_get_list"></a><h3>2.viii. acl_get_list</h3>
 200   
 201      <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>
 202   
 203      <div class="codebox"><pre>
 204  $user_id = array(2, 53);
 205  $permissions = array('f_list', 'f_read');
 206  $forum_id = array(1, 2, 3);
 207  $result = $auth-&gt;acl_get_list($user_id, $permissions, $forum_id);
 208  </pre></div>
 209   
 210      <p>The parameters may be of the following legal types:</p>
 211          <ul>
 212              <li><strong>$user_id</strong>: <code>false</code>, int, array(int, int, int, ...)</li>
 213              <li><strong>$permissions</strong>: <code>false</code>, string, array(string, string, ...)</li>
 214              <li><strong>$forum_id</strong>: <code>false</code>, int, array(int, int, int, ...)</li>
 215          </ul>
 216   
 217      <a name="misc"></a><h3>2.ix. Miscellaneous</h3>
 218   
 219      <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>
 220          <ul>
 221              <li><pre>function acl_group_raw_data($group_id = false, $opts = false, $forum_id = false)</pre></li>
 222              <li><pre>function acl_user_raw_data($user_id = false, $opts = false, $forum_id = false)</pre></li>
 223              <li><pre>function acl_raw_data_single_user($user_id)</pre></li>
 224              <li><pre>function acl_raw_data($user_id = false, $opts = false, $forum_id = false)</pre></li>
 225              <li><pre>function acl_role_data($user_type, $role_type, $ug_id = false, $forum_id = false)</pre></li>
 226          </ul>
 227   
 228      <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>
 229   
 230          </div>
 231   
 232          <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
 233   
 234          </div>
 235      </div>
 236   
 237      <hr />
 238   
 239  <a name="admin_related"></a><h2>3. Admin related functions</h2>
 240   
 241      <div class="paragraph">
 242          <div class="inner">
 243   
 244          <div class="content">
 245   
 246      <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>
 247   
 248      <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>
 249   
 250      <div class="codebox"><pre>
 251  $auth_admin = new auth_admin();</pre>
 252      </div>
 253   
 254      <p>This instance gives you access to both the methods of this specific class and that of <code>auth</code>.</p>
 255   
 256          </div>
 257   
 258          <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
 259   
 260          </div>
 261      </div>
 262   
 263      <hr />
 264   
 265  <a name="disclaimer"></a><h2>4. Copyright and disclaimer</h2>
 266   
 267      <div class="paragraph">
 268          <div class="inner">
 269   
 270          <div class="content">
 271   
 272      <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>
 273   
 274          </div>
 275   
 276          <div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>
 277   
 278          </div>
 279      </div>
 280   
 281  <!-- END DOCUMENT -->
 282   
 283      <div id="page-footer">
 284          <div class="version">&nbsp;</div>
 285      </div>
 286  </div></div>
 287   
 288  <div>
 289      <a id="bottom" accesskey="z"></a>
 290  </div>
 291   
 292  </body>
 293  </html>
 294