Simple Machines Community Forum

Please note this tutorial extends an already existing tuturial (http://www.simplemachines.org/community/index.php?topic=19136.0). It's aimed to show how a permission can be added and checked. It would most likely be useful for those who wish to write modifications of SMF.

Deciding on the type of permission
Before adding a permission you need to make some decisions on what the permission will be needed for.

1. Whether the permission will be a board permission or a membergroup permission. A board permission can be set differently for each board (e.g. make_sticky), while a membergroup permission can only be set globally (e.g. manage_membergroups).

2. Whether the permission will have two options or just one. For instance, the lock permission consists of two permissions: lock_own and lock_any for locking your own topics or any topics respectively.

3. The name. Chose a logical name that consists of lowercase letters, using underscores (_) as word seperators. The maximum length of a permission name is 30 characters.

4. The permission group to put the permission in. In the permission interface, the permissions are grouped (e.g. the 'Calendar' group contains calender_view, calendar_post, and calendar_edit). You can chose to add your own group, or insert your permission in an existing group. Remember that some of the permission groups (like 'Forum administration') are not visible when editing permissions for the guest group.

5. The restriction level of the permission: restrict, standard, moderator, maintenance. Use 'restrict' for low-security permissions, while 'maintenance' permissions you'd only give to those you really trust.


Adding the permission

1. Add the permission to one of the arrays that represents the chosen restriction level inside ManagePermisssions.php.

E.g. a high-security membergroup permission would be added after:
$groupLevels['global']['maintenance'] = array_merge($groupLevels['global']['moderator'], array(

while a low-security board permission would be added after:
$groupLevels['board']['restrict'] = array(

2. Add the permission to the $permissionList array in ManagePermissions.php. The array consists of four levels: 'membergroup'/'board' -> permission group -> permission -> whether it has multiple options or not. Based on the choices made above, you can insert the permission in the proper place.

E.g. to add a membergroup permission that should be in the 'general' permission group with no '_own' or '_any' variants, find:
$permissionList = array(
'membergroup' => array(
'general' => array(

Add after:
'my_permission' => false,

3. Add the language entries for each permission in the ManagePermissions language files.

For each permission, add:

$txt['permissionname_my_permission'] = 'My permission';
$txt['permissionhelp_my_permission'] = 'With "My Permission" you can take over the world.';

Also when the permission is not present, an error is shown. Add the error like this:

$txt['cannot_my_permission'] = 'Sorry, you\'re not allowed to use "My Permission"';

For each added permission group, add:

$txt['permissiongroup_my_permission_group'] = 'My permission group';


Adding default values for the new permission
If you want some groups to have the new permission by default, you need to run some database queries. Some examples:

Example: Add a certain membergroup permission (my_permission) to all registered members:
<?php
// Initialize the groups array with 'ungrouped members' (ID: 0).
$groups = array(0);

// Get all the non-postcount based groups.
$request = db_query("
SELECT ID_GROUP
FROM {$db_prefix}membergroups
WHERE minPosts = -1", __FILE__, __LINE__);
while ($row = mysql_fetch_assoc($request))
$groups[] = $row['ID_GROUP'];

// Give them all their new permission.
$request = db_query("
INSERT IGNORE INTO {$db_prefix}permissions
(permission, ID_GROUP, addDeny)
VALUES
('my_permission', " . implode(", 1),
('my_permission', ", $groups) . ", 1)", __FILE__, __LINE__);
?>

Example: Add a certain board permission (my_board_permission) to all registered members and guests
<?php
// Initialize the groups array with 'ungrouped members' (0) and guests (-1).
$groups = array(-1, 0);

// Get all the non-postcount based groups.
$request = db_query("
SELECT ID_GROUP
FROM {$db_prefix}membergroups
WHERE minPosts = -1", __FILE__, __LINE__);
while ($row = mysql_fetch_assoc($request))
$groups[] = $row['ID_GROUP'];

// Give them all their new global board permission.
$request = db_query("
INSERT IGNORE INTO {$db_prefix}board_permissions
(permission, ID_GROUP, ID_BOARD, addDeny)
VALUES
('my_board_permission', " . implode(", 0, 1),
('my_board_permission', ", $groups) . ", 0, 1)", __FILE__, __LINE__);
?>


Checking permissions
One the most important parts of permissions is to check whether someone has a permission or not. There are two ways to check the permission:

1. Conditional. Only checks the permission, and return wether the user has the permission (true) or not (false).

Example:
<?php
if (allowedTo('my_permission'))
take_over_the_world();
?>

2. Deterministic. Checks the permission and shows an error if you don't have clearance.

Example:
<?php
isAllowedTo('my_permission');

// At this point of the code, only those with my_permission are left.
// I can now safely assume you're authorized to...
take_over_the_world();
?>


There is no difference in checking membergroup or board permissions. A board permission check assumes you're inside a board, determined by the board or topic parameter given in the URL or as a $_POST variable (e.g. index.php?topic=x). If you want to check whether a user has permissions inside another board, use:
<?php
if (allowedTo('my_board_permission', $board_id_to_check))
take_over_the_world();
?>

or, if you want to know which boards a user has a certain permission use:
<?php
$my_boards = boardsAllowedTo('my_board_permission');

if (empty($my_boards))
{
// User has my_board_permission permission on no boards at all.
}
elseif ($my_boards[0] == 0)
{
// User has my_board_permission permission on ALL boards.
}
else
{
// User has my_board_permission permission on the boards that are in the $my_boards array.
}
?>

Quote from: Compuart on December 05, 2005, 11:33:58 AM
Add after:

Code Select Expand

'my_permission' => false,

Just checking, true here will make it be a own/all permission?

This is great :D After trying for ages before, I've now got my new permission in only 10 minutes.

Quote from: eldacar on December 05, 2005, 10:14:20 PM

Quote from: Compuart on December 05, 2005, 11:33:58 AM
Add after:

Code Select Expand

'my_permission' => false,

Just checking, true here will make it be a own/all permission?

Indeed. It would add 'my_permission_own' and 'my_permission_any'. You'd need to add two extra language strings as well:
$txt['permissionname_my_permission_own'] = 'Own llamas';
$txt['permissionname_my_permission_any'] = 'Any llamas';

Setting "$groups = array(0);" will give permission to ALL member groups?

Membergroup 0 is 'ungrouped members' (those members that have no primary membergroup set). $groups = array(0) initialializes the array of groups to that membergroup. After that, additional groups are added to the $groups array.

Oh ok.  Thanks.

well i have tryed this and i could not get it to work dam it grrrrrr

im trying to add permisstions for the shout box so guest cant see the shouts i had to hard code it so it was


if ($user_info['is_guest'])

echo '

        <td><b><center>Sorry only member can view the shout box please</center></B> </td>';   

esle

i added that just befor it foreach the shouts and it works

but i want to add in the admin section (guest can see shouts)
i tryed what you siad and it kinda worked once i put a tick in the box guest could not see the shouts but admins could not aswell it's like it set it to all the member groups

Use $context['user']['is_guest'].  You need to make $user_info a global to use it.

thay way i did it works fine but when try to make a custom permission it seems to set it for all groups like i make a tick in the guests permisssions to not shout the shouts but it seems to set it for the admins as well

whats up with that how can i fix it 

Make sure you added it to the group permission ection and not board permission.  Happened to me once.


$permissionList = array(
'membergroup' => array(
'general' => array(
    'my_permission' => false,
'view_stats' => false,
'view_mlist' => false,
'who_view' => false,
'search_posts' => false,
'karma_edit' => false,
'see_shouts' => false,


'see_shouts' => false,
it's in the member group

Admins can do everything. They automatically have every permission.
The false in that array means that it is a singular permission, not that the default is false or anything.

well what i have done seems to work i want to get this work and so i understand it all as the site im working on use's smf sofware and smf is very easy to work with im going to be adding banners but im also donig permissionds for them so paid members dont see banners and none paid members see banners if i can get this permissions sorted i can start working on the banner script who knows i might make a mod for it if it turns out well..lol


but the problem im having here is i have done what you have said as you can see there but when i goto lets say guest and tick it so guest cant see shouts it seems to stop admins from seeing them to????? all the other members can see them though

please help 

If admins are being blocked then your checking code is faulty.

Please post it too ;)

oh i did not do any database stuff would this be my problem?? im very unsure of what i have to do with the database

i have looked into the database and it seems to have just added them this is what it says

ID_GROUP 0
PERMISSION see_shouts
addDeny 1

im unsure of what that meens

Do you don't need to do any database stuff. Please post the code where you are checking this permission.

ok here is what i have done

ManagePermission.php

// Standard - ie. members.  They can do anything Restrictive can.
$groupLevels['global']['standard'] = array_merge($groupLevels['global']['restrict'], array(
    'cantsee_shouts',
    'see_shouts',
'view_mlist',
'karma_edit',
'pm_read',
'pm_send',
'profile_view_any',
'profile_extra_own',
'profile_server_avatar',
'profile_upload_avatar',
'profile_remote_avatar',
'profile_remove_own',

then

$permissionList = array(
'membergroup' => array(
'general' => array(
    'my_permission' => false,
'view_stats' => false,
'view_mlist' => false,
'who_view' => false,
'search_posts' => false,
'karma_edit' => false,
'see_shouts' => false,
'cantsee_shouts' => false,


ManagePermissions.template.php

$txt['permissionname_cantsee_shouts'] = 'cant see shouts';


and in my shout.template.php



opps sorry here is the code i put in
shout.template.php


if (allowedTo('cantsee_shouts'))
echo '
<tr class="', $alternate ? 'windowbg' : 'windowbg', '">
<td><b>Sorry only member can<br />view the shout box please</b> </td>';


else

foreach ($context['arc_shouts'] as $shout)


You shouldn't have two permissions. Use one, and if you want to test if they can't do it, use:
if (!allowedTo('see_shouts'))

yea i dont use 'see_shouts'

that was testing some else..lol

ok i tryed what you said and it did not work i put a tick in the box for guest not to view the shouts and thay still can
so this
if (!allowedTo('see_shouts'))

dont work
but
   if (allowedTo('cantsee_shouts'))
does work
but if i use the second one and then set it so guest cant see shouts it stop admins from seeing them as well
i dont see how this is possable as admins have all permission?

Use one permission: see_shouts.
If you want to test if someone can see the shouts use
if (allowedTo('see_shouts'))

if you want to test if they can't do it, use:
if (!allowedTo('see_shouts'))

wait it did work it was the ! i was missing...lol

Thank you very much this is really going to come in handy

i have some testing servers setup thats y i could not give you a url to go have a look once it works on the testing servers then i can do it on the main site...

once again thank you for your time on this im very very happy now :D..lol

befor i did

(!allowedTo('see_shouts'))

but im not useing see_shouts i dont think i set that up right anyway i have remove all the see_shouts permissions and im usering

if (!allowedTo('cantsee_shouts'))


Well i think it all works all do more testing but all looks ok from here]


once again thank you you guys are so very helpful

The ! means not, or the opposite. If allowedTo() is true, then !allowedTo() will be false.

It's always best to use as few permissions as possible, and the way SMF is set up, permissions should be to allow something, not to deny something. If you want to deny something, you make a permission to allow it and then deny a group.

Anyways, glad it's working now.

lol it looks all messed up i know so how would i make it to deny it then like your saying ??

i know you have spent anoth time on this already im sorry if you wantto get ion with other things you can..lol

but im all for learning new things:)

Eldacar,

Here we are again.   :)

I have created my own Permissions:

View Post
and
View Topic

They work pretty well, but when a Guest tries to look where he is not allowed Guest sees language that says please login or register to see this area.  

When Subscribe (membergroup) tries to access similarly protect areas, it just says An Error Has Occurred.  Obviously I want Subscribe to get to the same area as Guest when reaching an area not permitted.

I'm currently using in display.php to determine which membergroups can see posts:

isAllowedTo('view_post');

And in MessageIndex.php I'm using to determine which membergroups can see topics:

isAllowedTo('view_topic');


I'm just trying to clean it up so all members in a group not allowed to see those levels are redirected or simply see a message telling them to login with a login boxes.

Help me!!!   :)

Please use the correct terminology! I still don't understand you.
http://docs.simplemachines.org/index.php?board=11.0

Quote from: eldacar on June 06, 2006, 11:49:07 PM
Please use the correct terminology! I still don't understand you.
http://docs.simplemachines.org/index.php?board=11.0

I am using the correct terminology.

The Forum has Boards.  Those Boards have Topics.  Those Topics have Posts. 

I have set up Permissions determining whether or not a User can:

View Posts
and
View Topics.


I just want to make sure when a User in a Membergroup isn't permitted to view a post or view a topic they get a prompt to Register and an opportunity to Login.

But you can't view a topic without also viewing the posts, and vice versa.

Quote from: eldacar on June 07, 2006, 12:19:11 AM
But you can't view a topic without also viewing the posts, and vice versa.

Sure you can, afterall there is a different set of permissions for topics and posts.  Topics are what you see when you click on a Board.  Posts are what you see when you click on a Topic.

None of that is really the point.  Let's just deal with one of them for now to simplify things.  The point is I have set up a Permission, view_post. 

In display.php I have:

// The central part of the board - topic display.
function Display()
{
global $scripturl, $txt, $db_prefix, $modSettings, $context, $settings, $options, $sourcedir;
global $user_info, $ID_MEMBER, $board_info, $topic, $board, $attachments, $messages_request;

   

// Created my own Permission set to recognize View Post as a functional option in the Admin Permission panel.

isAllowedTo('view_post');

When my membergroup 'Subscribe' tries to access Posts in a Board where they are not permitted, they get An Error Has Occurred.  I would like for them to get to a Login page, which is what happens when my Guests have the same level of permissions.

That's all I need.

You are viewing a topic when you open it and read the posts it contains. You are viewing a board when you open it up to see the list of topics, which is done by the MessageList template. You don't need the view_topic permission if it means viewing a board, because that is what the access control lists are for.

Well, if they're already logged in but can't do something, they get an error message, not a log in box.

Quote from: eldacar on June 07, 2006, 01:38:02 AM
You are viewing a topic when you open it and read the posts it contains. You are viewing a board when you open it up to see the list of topics, which is done by the MessageList template. You don't need the view_topic permission if it means viewing a board, because that is what the access control lists are for.

Well, if they're already logged in but can't do something, they get an error message, not a log in box.

I don't want this at the Access Level because then those without that permission can't see the Board in list of Boards, and I don't put in code that I have to remember to change anytime I add a board.  I also want some boards hidden. 

With all due respect because I appreciate you're trying to help,you seem to getting bogged down in your terminology.  Let me start over.

There are Boards.
There are Topics.
There are Posts.

Access Level differentiates who can see a Board in the list of Boards.  (I'm not talking about that.)
There is nothing within the Permissions' section that differentiates who can view Topics within a Board.
There is nothing within the Permissions' section that differentiates who can view Posts within a Topic.

I have created these extra permissions.  They work.  They are restricting the access, for the most part, as I wish. 
I have the 'view_post' permission check in Display.php.
I have the 'view_topic' permission check in MessageIndex.php.


Can we please just focus on the 'view_post' part for the sake of simplicity?

I want a User when he gets to a place that Permission is restricting him from, viewing posts, to get a Login prompt.

The code you posted before should do that, but obviously only guests will get a login prompt, because users are already logged in. They will instead get an error message.

Quote from: eldacar on June 07, 2006, 08:19:28 AM
The code you posted before should do that, but obviously only guests will get a login prompt, because users are already logged in. They will instead get an error message.

I know that.  I'm trying to get around that.  When Users are logged in and try other things they aren't permitted to do they get a login prompt.

There has to be a way to prompt them to login.  Right?

I do appreciate your time.

What will logging in accomplish? They are already logged in.

Quote from: eldacar on June 07, 2006, 08:30:48 AM
What will logging in accomplish? They are already logged in.

A very good point.  Then I just need them to be pointed to a message saying they don't have permission to view this part of the forum, that they may need to 'subscribe' to see this part of the forum. 

Actually, I would tell them what subscription they would need to see that part of the forum.

I can't figure out how to change which message a User sees at that point.  I think I know where to add and/or change messages.

so instead of isAllowedTo(), use an if statement.

if (!allowedTo(view_whatever))
{
     Display a message telling them to subscribe.
}

Quote from: eldacar on June 07, 2006, 08:40:11 AM
so instead of isAllowedTo(), use an if statement.

if (!allowedTo(view_whatever))
{
     Display a message telling them to subscribe.
}

Where?  Which file?

Thanks.

well, wherever you use isAllowedTo, use that instead.

Here is what I have, but it didn't work.  I still just got the error note.


function Display()
{
global $scripturl, $txt, $db_prefix, $modSettings, $context, $settings, $options, $sourcedir;
global $user_info, $ID_MEMBER, $board_info, $topic, $board, $attachments, $messages_request;

   
if (!isAllowedTo('view_post'))
{
echo 'You do not have permission to read posts on this board.  You do not have the necessary subscription.'
;}

use allowedTo, not isAllowedTo.

How would I go about getting it to print it coinciding with or instead of the error message, just as it would print a login prompt for a Guest?

I got everything all figured out.  Thanks.

eldacar, I am hoping that you can help me sort something out. I am using Niko's Related Topics (http://mods.simplemachines.org/index.php?mod=189) modification with SMF 1.1 RC2 and by following the support topic (http://www.simplemachines.org/community/index.php?topic=49410.0) on it have been able to get it installed and running.  I am trying to add in checking for permissions on viewing a board to the modification and I ask here since it seems as if maybe Niko is no longer developing this modification.

I have examined existing SMF code in an attempt to do this in such areas of the code like Search but have not been able to find an acceptable solution. I believe that I can add the check into to the db_query but I seem to be missing something. There are three queries used.  The first simply returns all the related topics by using MATCH but I don't think I can add a check there (my msql knowledge is a bit weak).
$related = db_query("SELECT *, MATCH (ms.subject,ms.body) AGAINST ('{$mssub}') As Score  FROM {$db_prefix}messages As ms WHERE MATCH (ms.subject,ms.body) AGAINST ('{$mssub}') ORDER BY Score DESC LIMIT 0,10",__FILE__,__LINE__);

Once the initial query is made then  a while is used:
while($relTopic = mysql_fetch_array($related))
and the following queries are run:
$tox = db_query("SELECT * FROM {$db_prefix}topics As t,{$db_prefix}messages As ml WHERE t.ID_TOPIC='{$relTopic['ID_TOPIC']}' AND ml.ID_MSG = t.ID_LAST_MSG LIMIT 0,1",__FILE__,__LINE__);
$tox2 = db_query("SELECT * FROM {$db_prefix}topics As t,{$db_prefix}messages As ml WHERE t.ID_TOPIC='{$relTopic['ID_TOPIC']}' AND ml.ID_MSG = t.ID_FIRST_MSG LIMIT 0,1",__FILE__,__LINE__);

I tried using $user_info[query_see_board]
but I believe that is reliant on querying the board table AS b or reliant on the board number sent $_REQUEST.

Any insight you or others would have in this matter would be greatly appreciated.

I tried to solve the problem I wrote mine here:
http://www.simplemachines.org/community/index.php?topic=291427
With this guide, but I could not. Someone willing to help me in this?

is this still relevant to SMF 2.0 Rc1?

i wish to make some custom permissions.. i use SSI.php for quite a few pages. i currently use an php array of groups that "are allowed" to view these pages. however. when i copy the permissions of say "group xyza" to a new group.. "thinking it will work" i forget to add them to the php file.. :x

example:

$allowed_groups = array(1,2,3,11,10,12,13,14,15,16,17,18);

      $can_see = FALSE;
      foreach ($allowed_groups as $allowed)
         if (in_array($allowed, $user_info['groups']))
         {
            $can_see = TRUE;
            break;
         }
         
      if (!$can_see)
      { // die, user access denied! //
      if ($context['user']['is_guest'])
        {
            redirectexit('http://domain.org/index.php?action=login');
            }
            else
                {
                redirectexit('http://domain.org/');
                }
                } else { // show the page access granted! :o //
// the content
}


found it somewhere on the SMF site. but rather inconveinent..

thank you for answer.  ;)

Quote from: uberjon on February 15, 2009, 04:24:10 AM
is this still relevant to SMF 2.0 Rc1?

i wish to make some custom permissions.. i use SSI.php for quite a few pages. i currently use an php array of groups that "are allowed" to view these pages. however. when i copy the permissions of say "group xyza" to a new group.. "thinking it will work" i forget to add them to the php file.. :x

example:

Code Select Expand


$allowed_groups = array(1,2,3,11,10,12,13,14,15,16,17,18);

      $can_see = FALSE;
      foreach ($allowed_groups as $allowed)
         if (in_array($allowed, $user_info['groups']))
         {
            $can_see = TRUE;
            break;
         }
        
      if (!$can_see)
      { // die, user access denied! //
      if ($context['user']['is_guest'])
        {
            redirectexit('http://domain.org/index.php?action=login');
            }
            else
                {
                redirectexit('http://domain.org/');
                }
                } else { // show the page access granted! :o //
// the content
}


found it somewhere on the SMF site. but rather inconveinent..

Hello uberjon, I was going through some old topics, did you ever get this solved? If no, then you can look into ManagePermissions.php under loadAllPermissions for adding a permission. As far as its language string goes, it would be $txt['permissionname_<your permission name>']. Then you can perform a check using allowedTo('<permission name>'). It is sort of still applicable for SMF 2.0 RC 1, although things have moved a bit and some new things have been added.

Do I still have to modify the database to turn some permissions on by default, or is there an easier way in SMF 2?

This is for SMF 1, from the first post:

<?php
   // Initialize the groups array with 'ungrouped members' (ID: 0).
   $groups = array(0);

   // Get all the non-postcount based groups.
   $request = db_query("
      SELECT ID_GROUP
      FROM {$db_prefix}membergroups
      WHERE minPosts = -1", __FILE__, __LINE__);
   while ($row = mysql_fetch_assoc($request))
      $groups[] = $row['ID_GROUP'];

   // Give them all their new permission.
   $request = db_query("
      INSERT IGNORE INTO {$db_prefix}permissions
         (permission, ID_GROUP, addDeny)
      VALUES
         ('my_permission', " . implode(", 1),
         ('my_permission', ", $groups) . ", 1)", __FILE__, __LINE__);
?>

If so, could someone rewrite this to make it work with SMF 2?

Thanks.

It'll be same for SMF 2 as well, there is no other way in SMF 2. You just have to use $smcFunc DB functions and correct the column/table names. Rest is same.

Thanks, I'll give it a shot.