Blame Extras/phpBB/3.0.4/docs/auth_api.html

4c79b5
4c79b5
<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en" xml:lang="en">
4c79b5
<head>
4c79b5
4c79b5
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
4c79b5
<meta http-equiv="content-style-type" content="text/css" />
4c79b5
<meta http-equiv="content-language" content="en" />
4c79b5
<meta http-equiv="imagetoolbar" content="no" />
4c79b5
<meta name="resource-type" content="document" />
4c79b5
<meta name="distribution" content="global" />
4c79b5
<meta name="copyright" content="2007 phpBB Group" />
4c79b5
<meta name="keywords" content="" />
4c79b5
<meta name="description" content="This is an explanation of how to use the phpBB auth/acl API" />
4c79b5
<title>phpBB3 • Auth API</title>
4c79b5
4c79b5
<link href="stylesheet.css" rel="stylesheet" type="text/css" media="screen, projection" />
4c79b5
4c79b5
</head>
4c79b5
4c79b5
<body id="phpbb" class="section-docs">
4c79b5
4c79b5
4c79b5
	
4c79b5
	
4c79b5
		
4c79b5
			
4c79b5
4c79b5
			
4c79b5
				
4c79b5
				

Auth API

4c79b5
				

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

4c79b5
				

Skip

4c79b5
			
4c79b5
4c79b5
			
4c79b5
		
4c79b5
	
4c79b5
4c79b5
	
4c79b5
4c79b5
	
4c79b5
4c79b5
4c79b5
4c79b5
	

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

4c79b5
4c79b5
	

Auth API

4c79b5
4c79b5
	
4c79b5
		
4c79b5
4c79b5
		
4c79b5
4c79b5
    4c79b5
    	
  1. Introduction
  2. 4c79b5
    	
  3. Methods
  4. 4c79b5
    	
      4c79b5
      		
    1. acl
    2. 4c79b5
      		
    3. acl_get
    4. 4c79b5
      		
    5. acl_gets
    6. 4c79b5
      		
    7. acl_getf
    8. 4c79b5
      		
    9. acl_getf_global
    10. 4c79b5
      		
    11. acl_cache
    12. 4c79b5
      	
      4c79b5
      	
      4c79b5
      	
    13. Admin related functions
    14. 4c79b5
      	
    15. Copyright and disclaimer
    16. 4c79b5
      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      	
      4c79b5
      4c79b5
      	
      4c79b5
      4c79b5

      1. Introduction

      4c79b5
      4c79b5
      	
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      	

      What is it?

      4c79b5
      4c79b5
      	

      The auth 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.

      4c79b5
      4c79b5
      	

      Initialisation

      4c79b5
      4c79b5
      	

      To use any methods contained with the auth class it first needs to be instantiated. This is best achieved early in the execution of the script in the following manner:

      4c79b5
      4c79b5
      	
      4c79b5
      $auth = new auth();
      4c79b5
      	
      4c79b5
      4c79b5
      	

      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 auth_admin methods you will need to instantiate this separately but in the same way.

      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      	
      4c79b5
      4c79b5
      	
      4c79b5
      4c79b5

      2. Methods

      4c79b5
      4c79b5
      	
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      	

      Following are the methods you are able to use.

      4c79b5
      4c79b5
      	

      2.i. acl

      4c79b5
      	
      4c79b5
      	

      The acl 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:

      4c79b5
      4c79b5
      	
      4c79b5
      $auth->acl(userdata);
      4c79b5
      	
      4c79b5
      4c79b5
      	

      Where userdata is the array containing the aforementioned data.

      4c79b5
      4c79b5
      	

      2.ii. acl_get

      4c79b5
      4c79b5
      	

      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:

      4c79b5
      4c79b5
      	
      4c79b5
      $result = $auth->acl_get(option[, forum]);
      4c79b5
      	
      4c79b5
      4c79b5
      	

      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.

      4c79b5
      4c79b5
      	

      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.

      4c79b5
      4c79b5
      	

      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.

      4c79b5
      4c79b5
      	

      There are some special options or flags 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.

      4c79b5
      4c79b5
      	

      2.iii. acl_gets

      4c79b5
      4c79b5
      	

      This method is funtionally similar to acl_get 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 acl_get twice.

      4c79b5
      4c79b5
      	

      The method should be called thus:

      4c79b5
      4c79b5
      	
      4c79b5
      $result = $auth->acl_gets(option1[, option2, ..., optionN, forum]);
      4c79b5
      	
      4c79b5
      4c79b5
      	

      As with the acl_get method the options are strings representing the required permissions to check. The forum again is an integer representing a given forum_id.

      4c79b5
      4c79b5
      	

      The method will return a positive integer if acl_get for one of the options evaluates to a positive integer (combines permissions with OR).

      4c79b5
      4c79b5
      	

      2.iv. acl_getf

      4c79b5
      4c79b5
      	

      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:

      4c79b5
      4c79b5
      	
      4c79b5
      $result = $auth->acl_getf(option[, clean]);
      4c79b5
      	
      4c79b5
      4c79b5
      	

      Just like in the acl_get 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.

      4c79b5
      4c79b5
      	

      The method returns an associative array of the form:

      4c79b5
      4c79b5
      	
      4c79b5
      array(forum_id1 => array(option => integer), forum_id2 => ...)
      4c79b5
      	
      4c79b5
      4c79b5
      	

      Where option is the option passed to the method and integer is either zero or a positive integer and the same acl_get(option, forum_id) would return.

      4c79b5
      4c79b5
      	

      2.v. acl_getf_global

      4c79b5
      4c79b5
      	

      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 acl_getf(option, true) returned one or more forums but it's faster. It should be called in the following way:

      4c79b5
      4c79b5
      	
      4c79b5
      $result = acl_getf_global(option)
      4c79b5
      	
      4c79b5
      4c79b5
      	

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

      4c79b5
      4c79b5
      	

      This method returns either zero or a positive integer.

      4c79b5
      4c79b5
      	

      2.vi. acl_cache

      4c79b5
      4c79b5
      	

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

      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      	
      4c79b5
      4c79b5
      	
      4c79b5
      4c79b5

      3. Admin related functions

      4c79b5
      4c79b5
      	
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      	

      A number of additional methods are available related to auth. 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, auth_admin. This can be found in includes/acp/auth.php.

      4c79b5
      4c79b5
      	

      To use any methods this class contains it first needs to be instantiated separately from auth. This is achieved in the same way as auth:

      4c79b5
      4c79b5
      	
      4c79b5
      $auth_admin = new auth_admin();
      4c79b5
      	
      4c79b5
      4c79b5
      	

      This instance gives you access to both the methods of this specific class and that of auth.

      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      	
      4c79b5
      4c79b5
      	
      4c79b5
      4c79b5

      4. Copyright and disclaimer

      4c79b5
      4c79b5
      	
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      	

      This application is opensource software released under the GPL. Please see source code and the docs directory for more details. This package and its contents are Copyright (c) 2000, 2002, 2005, 2007 phpBB Group, All Rights Reserved.

      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      4c79b5
      		
      4c79b5
      	
      4c79b5
      4c79b5
      4c79b5
      4c79b5
      	
      4c79b5
      		
      $Id: auth_api.html 8479 2008-03-29 00:22:48Z naderman $
      4c79b5
      	
      4c79b5
      4c79b5
      4c79b5
      4c79b5
      	
      4c79b5
      4c79b5
      4c79b5
      </body>
      4c79b5
      </html>