Tutorial.Permissions

Permission types

 * Admin permissions
 * Moderator permissions
 * User permissions
 * Forum permissions

Global permission
To check if user can for example view other users' profiles, use this code: if (!$auth->acl_get('u_viewprofile')) {    trigger_error('NOT_AUTHORISED'); } If he doesn't have permission to do it, he will see only error message and script will stop executing (exit) after trigger_error.

Local permission
If you want to check a local permission, for example to read posts on forum with ID 5, use this code: if (!$auth->acl_get('f_read', 5)) {    trigger_error('NOT_AUTHORISED'); }

Full list of existing permissions is in your database, in phpbb_acl_options table.

Adding a permission
Adding new permissions to Olympus is simple. NOTE: The permission can not contain a capital letter, this causes trouble later on if you try and create a module that needs this permission

Example how to add a permission to control who can access and manage foo:

Using the API (recommended)
acl_add_option(array( 'local'     => array, 'global'  => array('u_view_foo', 'u_manage_foo') )); ?>

Sample install page using API to add permission options
If you aren't otherwise using an installer for your mod, you can add a page under the install folder called something like install/install_permissions.php that would include something like the following code: <?php

/**
 * install script to set up permission options in the db for foo mod
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License

/**
 * @ignore

// initialize the page define('IN_PHPBB', true); define('IN_INSTALL', true); $phpbb_root_path = (defined('PHPBB_ROOT_PATH')) ? PHPBB_ROOT_PATH : './../'; $phpEx = substr(strrchr(__FILE__, '.'), 1); include($phpbb_root_path . 'common.' . $phpEx);

// Start session management $user->session_begin; $auth->acl($user->data); $user->setup('mods/foo');

// Setup $auth_admin class so we can add tabulated survey permission options include($phpbb_root_path . 'includes/acp/auth.' . $phpEx); $auth_admin = new auth_admin;

// Add foo permissions as local permissions // (you could instead make them global permissions by making the obvious changes below) $auth_admin->acl_add_option(array( 'local'		=> array('f_survey_design', 'f_survey_takeforothers', 'f_survey_viewhiddenresults'), 'global'	=> array ));

$message = $user->lang['ADDED_PERMISSIONS']. '

'; $message .= $user->lang['REMOVE_INSTALL']; trigger_error($message);

?> Then, add the following entry in language/en/mods/foo.php (or if you have no language file for the mod, add the following entry to language/en/common.php): 'ADDED_PERMISSIONS'	=> 'You have successfully added foo permission options to your database.',

Using SQL
You can also directly insert new rows into the phpbb_acl_options table: INSERT INTO phpbb_acl_options (auth_option, is_global, is_local, founder_only) VALUES ('u_view_foo', 1, 0, 0); INSERT INTO phpbb_acl_options (auth_option, is_global, is_local, founder_only) VALUES ('u_manage_foo', 1, 0, 0); Please note that you need to clear the cache by either: OR
 * deleting  and


 * executing

... after inserting the SQL manually.

Language file (Adding tabs)
In both cases it is highly recommended to add language variables for the permissions just added. To do this, simply create a file named permissions_foo.php in language/xx/mods. It will automatically be included, don't worry about how. <?php /** if (!defined('IN_PHPBB')) {	exit; }
 * DO NOT CHANGE

if (empty($lang) || !is_array($lang)) {	$lang = array; }

// DEVELOPERS PLEASE NOTE // // All language files should use UTF-8 as their encoding and the files must not contain a BOM. // // Placeholders can now contain order information, e.g. instead of // 'Page %s of %s' you can (and should) write 'Page %1$s of %2$s', this allows // translators to re-order the output of data while ensuring it remains correct // // You do not need this where single placeholders are used, e.g. 'Message %d' is fine // equally where a string contains only two placeholders which are used to wrap text // in a url you again do not need to specify an order e.g., 'Click %sHERE%s' is fine

// Adding new category $lang['permission_cat']['foo'] = 'Foo management';

// Adding the permissions $lang = array_merge($lang, array( 'acl_u_view_foo'   => array('lang' => 'Can view foo', 'cat' => 'foo'), 'acl_u_manage_foo'   => array('lang' => 'Can manage foo', 'cat' => 'foo'), )); ?> In this code they added the category "foo" (will be displayed as a new tab). All language keys where the key cat is equal to "foo" will be displayed in this tab. So you have created an new tab if you use that code.

The permission should be ready to assign to users/groups in the acp now. To check whether the logged in user has the nescessary permission to view foo, use this code: if (!$auth->acl_get('u_view_foo')) {    trigger_error('NOT_AUTHORISED'); }

Panels (in the ACP)
To get the permission to show up under the right panel you need to use correct naming. a_foo_bar : Administrator permissions panel m_foo_bar : Moderator permissions panel u_foo_bar : User permissions panel f_foo_bar : Forum permissions panel If you use the correct naming and give the permission a category in the language file as described above the permission will show in the selected panel.

Alternative method - using UMIL
The Unified MOD Install Library (UMIL) provides a number of functions for managing permissions:
 * permission_exists : Check if a permission (auth) setting exists.
 * permission_add : Add a permission (auth) option
 * permission_remove : Remove a permission (auth) option
 * permission_set : Allows you to set permissions for a certain group/role
 * permission_unset : Allows you to remove permissions from a certain group/role (basically setting their permission to ‘No’)

For more information on creating a UMIF (Unified MOD Install File) using the UMIL and the permissions functions see the UMIL Documentation, UMIL Examples, and UMIL Overview.

Tutorial.Permissions