phpbb3/phpBB/docs/auth_api.html at develop · sayedather/phpbb3 · GitHub

History

292 lines (190 loc) · 12.7 KB

Raw

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

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

<!DOCTYPE html>

<head>

<title>phpBB3 • Auth API</title>

</head>

<p>This is an explanation of how to use the phpBB auth/acl API</p>

</div>

</div>

<p>This is an explanation of how to use the phpBB auth/acl API.</p>

<ol>

<li><a href="#intro">Introduction</a></li>

<li><a href="#methods">Methods</a>

<li><a href="#acl_getf_global">acl_getf_global</a></li>

<li><a href="#acl_cache">acl_cache</a></li>

<li><a href="#acl_clear_prefetch">acl_clear_prefetch</a></li>

<li><a href="#misc">Miscellaneous</a></li>

</ol>

</li>

<li><a href="#admin_related">Admin related functions</a></li>

<li><a href="#disclaimer">Copyright and disclaimer</a></li>

</ol>

</div>

</div>

<hr />

<a name="intro"></a><h2>1. Introduction</h2>

<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>

<h4>Initialisation</h4>

<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>

$auth = new phpbb_auth();

</pre></div>

<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>

</div>

</div>

<hr />

<a name="methods"></a><h2>2. Methods</h2>

<p>Following are the methods you are able to use.</p>

<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>

$auth->acl(<code>userdata</code>);

</pre></div>

<p>Where userdata is the array containing the aforementioned data.</p>

<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>

$result = $auth->acl_get(<code>option</code>[, <code>forum</code>]);

</pre></div>

<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>

<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>

<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>

<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>

<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>

<p>The method should be called thus:</p>

$result = $auth->acl_gets(<code>option1</code>[, <code>option2</code>, ..., <code>optionN</code>, <code>forum</code>]);

</pre></div>

<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>

<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>

<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>

$result = $auth->acl_getf(<code>option</code>[, <code>clean</code>]);

</pre></div>

<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>

<p>The method returns an associative array of the form:</p>

array(<em>forum_id1</em> => array(<em>option</em> => <em>integer</em>), <em>forum_id2</em> => ...)

</pre></div>

<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>

<a name="acl_getf_global"></a><h3>2.v. acl_getf_global</h3>

<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>

$result = $auth->acl_getf_global(<code>option</code>)

</pre></div>

<p>As with the previous methods option is a string specifying the permission which has to be checked.</p>

<p>This method returns either zero or a positive integer.</p>

<a name="acl_cache"></a><h3>2.vi. acl_cache</h3>

<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>

<a name="acl_clear_prefetch"></a><h3>2.vii. acl_clear_prefetch</h3>

<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>

// clear stored permissions for user 2

$user_id = 2;

$auth->acl_clear_prefetch($user_id);

</pre></div>

<p>This method returns void.</p>

<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>

$user_id = array(2, 53);

$permissions = array('f_list', 'f_read');

$forum_id = array(1, 2, 3);

$result = $auth->acl_get_list($user_id, $permissions, $forum_id);

</pre></div>

<p>The parameters may be of the following legal types:</p>

<ul>

<li><strong>$user_id</strong>: <code>false</code>, int, array(int, int, int, ...)</li>

<li><strong>$permissions</strong>: <code>false</code>, string, array(string, string, ...)</li>

<li><strong>$forum_id</strong>: <code>false</code>, int, array(int, int, int, ...)</li>

</ul>

<a name="misc"></a><h3>2.ix. Miscellaneous</h3>

<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>

<ul>

<li><pre>function acl_group_raw_data($group_id = false, $opts = false, $forum_id = false)</pre></li>

<li><pre>function acl_user_raw_data($user_id = false, $opts = false, $forum_id = false)</pre></li>

<li><pre>function acl_raw_data_single_user($user_id)</pre></li>

<li><pre>function acl_raw_data($user_id = false, $opts = false, $forum_id = false)</pre></li>

<li><pre>function acl_role_data($user_type, $role_type, $ug_id = false, $forum_id = false)</pre></li>

</ul>

<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>

</div>

</div>

<hr />

<a name="admin_related"></a><h2>3. Admin related functions</h2>

<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>

<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>

$auth_admin = new auth_admin();

</pre></div>

<p>This instance gives you access to both the methods of this specific class and that of <code>auth</code>.</p>

</div>

</div>

<hr />

<a name="disclaimer"></a><h2>4. Copyright and disclaimer</h2>

<p>This application is opensource software released under the <a href="http://opensource.org/licenses/gpl-2.0.php">GNU General Public License v2</a>. Please see source code and the docs directory for more details. This package and its contents are Copyright (c) <a href="http://www.phpbb.com/">phpBB Group</a>, All Rights Reserved.</p>

</div>

</div>

</div>

</div></div>

<div>

</div>

</body>

</html>

phpbb3/phpBB/docs/auth_api.html at develop · sayedather/phpbb3 · GitHub

Expand file tree

Breadcrumbs

auth_api.html

Latest commit

History

Breadcrumbs

auth_api.html

File metadata and controls