| Authenticating an Action |
| Description: Demonstrates how to create an AUTH_ constant and integrate it into the Forum Permissions and Group Permissions ACP panels. |
| Author: Fountain of Apples |
| Date: Thu Dec 08, 2005 4:37 am |
| Type: HowTo |
| Keywords: auths,authentication,system,phpBB,constant,permissions,MODs,tutorial,howto,demonstration |
| Category: MODifications |
 |
First off, before we begin...
What is Authentication?
The phpBB Authentication System (auths system for short) is the area that lets you control who can do what on your forum. Basically, it's what allows you to differentiate between a guest user, a registered user, a member of a certain usergroup, and a moderator, and what their "powers" on your board are. (The auths system doesn't apply to administrators; they get full reign over the board.)
The most commonly used part of the auths system is your Forum Permissions panel in the ACP. Here, you can control who can view each forum, who can post and reply in it, who can edit and delete topics, etc., (but that's another tutorial). The Usergroups Permissions panel is also a part of the auths system, which basically controls which forums a group can moderate and which private forums groups have access to.
With phpBB's auth system, you can't deny permission but only grant. For example, you can't make it so one user can't view a forum while everyone else can. You can only create a forum and then grant people permission to view it.
Why and Where Should I Use it in my MOD?
The phpBB2 auths system is forum-by-forum-based. The auths system is not used to determine if a user can send private messages or host an avatar; that's handled in a different section of phpBB. Therefore, you should only use this system if your MOD does things related to forums or topics.
The auths system is what you should use if you want to provide some users access to a feature but not others. For example, an authentication setting is available to limit which users can make stickies or announcements, however there is no authentication setting to specifically limit who can search through a forum (however Search does respect the authentication settings of who can view a forum, i.e. it won't return results from a hidden forum).
How this Article Works
Setting up an authentication setting is quite straightforward. In this article, we are going to set up authentication for the FooBar action. When coding your MOD, you will want to replace FooBar with the name of your action. When "foobar" is used in code (without quotes), the action must be in lowercase. When "FOOBAR" is used in code (without quotes), the action must be in uppercase. When "FooBar" is used in code (without quotes), it can be written normally.
I'm Ready. Let's Get Started!
The first place we are going to start is admin/admin_forumauth.php, so open this file. This file is the ACP Forum Permissions file, where the permissions are set.
The first thing we are going to do in here is define the authentication settings for the Simple Mode presets. If you look in your Forum Permissions, you will see there is a Simple Mode and an Advanced Mode. In Simple Mode, the admin can specify an authentication preset, and all the settings will be set accordingly.
First of all, there's an SQL query you will need to run; this can be handled by the SQL action: | Code: | | ALTER TABLE phpbb_auth_access ADD auth_foobar TINYINT( 1 ) DEFAULT '1' NOT NULL; |
The next thing you should do is decide what settings you want for each preset. Use your good judgement based on the average use of your MOD for each preset. The different presets are:
Public -- Guests can view, read, post, and reply in the forum. Registered users can also edit and delete their posts, as well as vote and create polls. Moderators also have moderation powers.
Registered -- Guests can view the forum and read the posts. Registered users can also post and reply in the forum, edit and delete their posts, as well as vote and create polls. Moderators also have moderation powers.
Registered [Hidden] -- Same as Registered except the forum will not be displayed for guest users.
Private -- Guests and Registered users can view the forum and read the posts. Registered users in specified groups can also post and reply in the forum, edit and delete their posts, as well as vote and create polls. Moderators also have moderation powers.
Private [Hidden] -- Same as Private except the forum will not be displayed for guests and registered users who don't have permission to post.
Moderators -- Guests and Registered Users can view the forum and read the posts. Only Moderators can do everything else.
Moderators [Hidden] -- Same as Moderators except the forum will not be displayed to non-moderators.
When making the next few edits, you will be inserting a constant which designates which users will have the permission. The following constants are available:
AUTH_ALL -- All users and guests have permission.
AUTH_REG -- Only registered users have permission.
AUTH_ACL -- Only users in admin-specified groups have permission.
AUTH_MOD -- Only moderators and administrators have permission.
AUTH_ADMIN -- Only administrators have permission.
Now, to start the coding. The way the instructions are written here are how you will want to do them in your MOD.
Find:
In-Line Find:
In-Line After, Add:
This is just a courtesy to act as a key to the next set of lines.
Find:
In-Line Find: | Code: | | AUTH_MOD, AUTH_REG, AUTH_REG |
In-Line After, Add:
Here, you are adding the constant listed above that corresponds to the Public preset (AUTH_ALL is the example used here).
Find:
In-Line Find: | Code: | | AUTH_MOD, AUTH_REG, AUTH_REG |
In-Line After, Add:
Here, you are adding the constant listed above that corresponds to the Registered preset (AUTH_REG is the example used here).
Find:
In-Line Find: | Code: | | AUTH_MOD, AUTH_REG, AUTH_REG |
In-Line After, Add:
Here, you are adding the constant listed above that corresponds to the Registered [Hidden] preset (AUTH_REG is the example used here).
Find:
In-Line Find: | Code: | | AUTH_MOD, AUTH_ACL, AUTH_ACL |
In-Line After, Add:
Here, you are adding the constant listed above that corresponds to the Private preset (AUTH_ACL is the example used here).
Find:
In-Line Find: | Code: | | AUTH_MOD, AUTH_ACL, AUTH_ACL |
In-Line After, Add:
Here, you are adding the constant listed above that corresponds to the Private [Hidden] preset (AUTH_ACL is the example used here).
Find:
In-Line Find: | Code: | | AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD |
In-Line After, Add:
Here, you are adding the constant listed above that corresponds to the Moderators preset (AUTH_MOD is the example used here).
Find:
In-Line Find: | Code: | | AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD, AUTH_MOD |
In-Line After, Add:
Here, you are adding the constant listed above that corresponds to the Moderators [Hidden] preset (AUTH_MOD is the example used here).
Phew, now that that's done, the rest of the file is pretty straightforward:
Find: | Code: | | $forum_auth_fields = array( |
In-Line Find:
In-Line After, Add:
Find: | Code: | | 'auth_pollcreate' => $lang['Pollcreate'], |
Before, Add: | Code: | | 'auth_foobar' => $lang['FooBar'], |
Now, we move on to admin/admin_ug_auth.php. This is the file that will allow you to specify which usergroups get that "Private" access to forums, and the coding is a bit more straightforward:
Find: | Code: | | $forum_auth_fields = array( |
In-Line Find:
In-Line After, Add:
Find: | Code: | | 'auth_pollcreate' => AUTH_POLLCREATE); |
Before, Add: | Code: | | 'auth_foobar' => AUTH_FOOBAR, |
Find: | Code: | | 'auth_pollcreate' => $lang['Pollcreate']); |
Before, Add: | Code: | | 'auth_foobar' => $lang['FooBar']); |
Next, we'll move on to includes/auth.php. This file manages the SQL required for setting up the auths table and gets the authentication for the current user. Its changes are also straightforward:
Find: | Code: | | $a_sql = 'a.auth_view, a.auth_read |
In-Line Find:
In-Line After, Add:
Find: | Code: | | $auth_fields = array('auth_view', 'auth_read' |
In-Line Find:
In-Line After, Add:
Find: | Code: | $auth_fields = array('auth_vote');
break; |
After, Add: | Code: | case AUTH_FOOBAR:
$a_sql = 'a.auth_foobar';
$auth_fields = array('auth_foobar');
break; |
Next, we'll move on to includes/constants.php. This is where we define our AUTH_ Constants. Note that you will need to reserve some AUTH_ Constants to use in your MOD; we do these reservations so MODs don't clash.
Find: | Code: | | define('AUTH_ATTACH', 11); |
After, Add: | Code: | | define('AUTH_FOOBAR', 5); |
Here you will replace 5 with your AUTH_ constant number. Note that you cannot use 5, because that one is already used by phpBB.
And lastly, we're just going to define our $lang var we set up earlier in language/lang_english/lang_admin.php.
Find: | Code: | | $lang['Pollcreate'] = 'Poll create'; |
After, Add: | Code: | | $lang['FooBar'] = 'FooBar'; |
Now it's coded, but How do I Use It?
Now that our FooBar auth is coded, we need to use it to determine if a user can do things or not. Luckily, we don't need to do fancy SQL queries, because phpBB does it for us, and puts the results in an $is_auth array. All we need to do is check $is_auth['auth_foobar'] in an if statement, like this:
| Code: | if ($is_auth['auth_foobar'])
{
message_die(GENERAL_MESSAGE, 'Yes, you have permission to do FooBar!');
}
else
{
message_die(GENERAL_MESSAGE, 'Sorry, you don't have permission to do FooBar.');
} |
That's it! |
|
|
|
