Adding custom permissions

Using SMF's inbuilt permissions system is an easy way for ensuring that any custom actions or mods are protected securely. Adding a new permission and then checking it for these custom actions is not hard.

New Permissions

Firstly, the name of the new permission must be decided. Choose something simple that consists of lowercase letters and underscores as word seperators, and which describes what the permission will actually be used for. The maximum length of a permission name is 30 characters. If you are writing a mod, consider using a prefix of either your nickname or the mod's name.

The next decision to make is whether it will be the new permission will be a board permission or a global membergroup permission. This should be fairly simple, if the permission has anything to do with boards topics or posts then it should be a board permission, otherwise it should be a membergroup permission.

You can either place your permission in an existing permission group, or make a new group. If you want to make a new permission group, then the name of that group has the same restrictions as permission names do.

Lastly you must decide whether the new permission will have two permission options. For example, the lock permission consists of two permissions: lock_own and lock_any for locking your own topics or any topics respectively.

Now to finally add the permission! Open ManagePermissions.php in your favourite text editor and find the following line:

// Load all the permissions that can not be given to guests.

Above that line you will put the code which adds your new permission.

New permissions in an existing group

The following code shows the general format for adding new permissions in an existing group:

$permissionList[A][B][C] = D;

A is the option to say whether it will be a membergroup or board permission. It must be precisely 'membergroup' or 'board' respectively. B is the permission group to add your new permission to. It must also be in quotes. C is the name of the new permission. It must be in quotes. D determines whether the permission will have two options or not. Use true if it does and false if it does not. Do not use quotes.

The following examples will hopefully explain this more clearly:

<?php

	// Add a new membergroup permission, in the maintenance section.
	$permissionList['membergroup']['maintenance']['new_maintenance_permission'] = false;

	// Add a new board permission with in the poll section with two options.
	$permissionList['board']['poll']['new_poll_options'] = true;

?>

New permissions in a new group

The following code shows the general format for adding new permissions in a new group:

$permissionList[A][B] = array(C => D);

A is the option to say whether it will be a membergroup or board permission. It must be precisely 'membergroup' or 'board' respectively. B is the permission group to add your new permission to. It must also be in quotes. C is the name of the new permission. It must be in quotes. D determines whether the permission will have two options or not. Use true if it does and false if it does not. Do not use quotes.

The following examples will hopefully explain this more clearly:

<?php

	// Add a new membergroup permission in a new group.
	$permissionList['membergroup']['my_new_group'] = array('my_new_permission' => false);

	// Add two new permissions into a new group.
	$permissionList['membergroup']['my_new_group'] = array(
		'my_new_permission_A' => false,
		'my_new_permission_B' => false,
	);

?>

New language entries

Each new permission will need at least three new language entries. $txt['permission...'] entries go in ManagePermissions.language.php and $txt['cannot...'] entries go in Errors.language.php, or if you're writing a mod put them all in Modifications.language.php.

You will need to add $txt['permissionname_newpermission'], $txt['permissionhelp_newpermission'] and $txt['cannot_newpermission'], and you might need to add $txt['permissionname_newpermission_own'], $txt['permissionname_newpermission_any'] and $txt['permissiongroup_newpermissiongroup']. The following examples will show what each is used for:

<?php

	// A short description for the permission
	$txt['permissionname_new_maintenance_permission'] = 'Maintain the forum';
	// A longer desciption
	$txt['permissionhelp_new_maintenance_permission'] = 'Messing around with the database to optimise and fix it and more fun stuff.';
	// What about if they can not do this?
	$txt['cannot_new_maintenance_permission'] = 'Sorry, but you can\'t maintain the forum.';

	$txt['permissionname_new_poll_options'] = 'Special poll options';
	$txt['permissionhelp_new_poll_options'] = 'Special poll options allow you to see who has voted for each option.';
	// Because this poll has multiple options, two new language entries are needed
	$txt['permissionname_new_poll_options_own'] = 'own polls';
	$txt['permissionname_new_poll_options_any'] = 'all polls';
	$txt['cannot_new_poll_options'] = 'Sorry, but you can\'t see who voted.';

	// New permission groups need a name too
	$txt['permissiongroup_my_new_group'] = 'Example group';

?>

That's it!

That's all you need to do to add new permissions. The remaining sections of this document are optional, but you might like to read over them as well.

Adding permissions in a different order

The example permissions above will always be added at the end of the permissions list. If you want the new group to be in a specific place or different order, you will have to edit the $permissionList array when it is first defined. This isn't difficult, just follow the format of the standard permissions.

Allowing permissions in all groups

If you're writing a mod you might want to make your permission allowed by default. You can do this by adding a php code file to your mod, with the following code (adjusted to your permission's name of course!):

<?php

	// Initialize the groups array with 'ungrouped members' (ID: 0).
	// Add -1 to this array if you want to give guests the same permission
	$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($groups) . ", 1)", __FILE__, __LINE__);

?>

To add a board permission, replace the last query with the following:

<?php

	// 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($groups) . ", 0, 1)", __FILE__, __LINE__);

?>