Contents of /contributions/modules/permissions_api/README

; $Id: README,v 1.7 2009/05/13 15:32:25 ebeyrent Exp $

The permissions_api module provides a method for adding and removing permissions from a given role.  This module helps with the issue of staging a Drupal site across multiple environments, from development sandbox to production environment.  

A specific example includes importing a CCK content type definition via hook_update in a custom module:

<?php
// Configure the path to the cck content type definition
$modulepath = drupal_get_path ('module', 'some_module');
$cck_definition_file = $modulepath.'/content_types/front_page_flash.php';
$values['type_name'] = '<create>';
$values['macro'] = file_get_contents($cck_definition_file);
 
include_once( drupal_get_path('module', 'node') .'/content_types.inc');
include_once( drupal_get_path('module', 'content') .'/content_admin.inc');
 
// Import the cck content type
drupal_execute("content_copy_import_form", $values); 
?>

This is great until you decide that you want members of specific roles to be able to do something with this content type.  Currently, the only way to grant the permissions is to navigate through the access control page in the admin interface, which is completely unusable if you have a lot of roles and a lot of modules.

This module addresses that problem by providing two functions:

permissions_grant_permissions()
permissions_revoke_permissions()

Each function accepts a role name and an array of permissions.  Sample usage would be:

<?php
function mymodule_update_1(){
  // Handle roles and permissions
  $permissions = array(
    'create some_content_type content',
    'edit some_content_type content',
    'edit own some_content_type content',
  );
  permissions_grant_permissions('some custom role', $permissions);  
}
?> 

This module also provides functions for granting all permissions defined by a given module to a given role, as well as granting all defined permissions to a given role, which is useful for creating admin-type roles.  Sample usage would be:

<?php
function mymodule_update_2(){
  // Create a "super-admin" role by granting all permissions
  permissions_grant_all_permissions('some admin role');  
}
?>

The next example shows how to grant all permissions defined by a specific module to a specific role:

<?php
function mymodule_update_3(){
  // Grant all permissions defined by a module's hook_perm implementation
  permissions_grant_all_permissions_by_module('some custom module', 'some module')
}
?>

Permissions API also allows you "clone" a role's permissions, so that a role can inherit all the permissions assigned to another role:

<?php
function mymodule_update_4(){
  permissions_role_inherit('my new role', 'role to clone');
}

INSTALLATION
------------

Install and enable the permissions_api Drupal module as you would any Drupal module.


CREDITS
-------
Developed and maintained by Erich Beyrent <erich [dot] beyrent [at] beyrent [dot] net>
Sponsored by CommonPlaces e-Solutions, LLC <http://www.commonplaces.com/>


1	; $Id: README,v 1.7 2009/05/13 15:32:25 ebeyrent Exp $
2
3	The permissions_api module provides a method for adding and removing permissions from a given role. This module helps with the issue of staging a Drupal site across multiple environments, from development sandbox to production environment.
4
5	A specific example includes importing a CCK content type definition via hook_update in a custom module:
6
7	<?php
8	// Configure the path to the cck content type definition
9	$modulepath = drupal_get_path ('module', 'some_module');
10	$cck_definition_file = $modulepath.'/content_types/front_page_flash.php';
11	$values['type_name'] = '<create>';
12	$values['macro'] = file_get_contents($cck_definition_file);
13
14	include_once( drupal_get_path('module', 'node') .'/content_types.inc');
15	include_once( drupal_get_path('module', 'content') .'/content_admin.inc');
16
17	// Import the cck content type
18	drupal_execute("content_copy_import_form", $values);
19	?>
20
21	This is great until you decide that you want members of specific roles to be able to do something with this content type. Currently, the only way to grant the permissions is to navigate through the access control page in the admin interface, which is completely unusable if you have a lot of roles and a lot of modules.
22
23	This module addresses that problem by providing two functions:
24
25	permissions_grant_permissions()
26	permissions_revoke_permissions()
27
28	Each function accepts a role name and an array of permissions. Sample usage would be:
29
30	<?php
31	function mymodule_update_1(){
32	// Handle roles and permissions
33	$permissions = array(
34	'create some_content_type content',
35	'edit some_content_type content',
36	'edit own some_content_type content',
37	);
38	permissions_grant_permissions('some custom role', $permissions);
39	}
40	?>
41
42	This module also provides functions for granting all permissions defined by a given module to a given role, as well as granting all defined permissions to a given role, which is useful for creating admin-type roles. Sample usage would be:
43
44	<?php
45	function mymodule_update_2(){
46	// Create a "super-admin" role by granting all permissions
47	permissions_grant_all_permissions('some admin role');
48	}
49	?>
50
51	The next example shows how to grant all permissions defined by a specific module to a specific role:
52
53	<?php
54	function mymodule_update_3(){
55	// Grant all permissions defined by a module's hook_perm implementation
56	permissions_grant_all_permissions_by_module('some custom module', 'some module')
57	}
58	?>
59
60	Permissions API also allows you "clone" a role's permissions, so that a role can inherit all the permissions assigned to another role:
61
62	<?php
63	function mymodule_update_4(){
64	permissions_role_inherit('my new role', 'role to clone');
65	}
66
67	INSTALLATION
68	------------
69
70	Install and enable the permissions_api Drupal module as you would any Drupal module.
71
72
73	CREDITS
74	-------
75	Developed and maintained by Erich Beyrent <erich [dot] beyrent [at] beyrent [dot] net>
76	Sponsored by CommonPlaces e-Solutions, LLC <http://www.commonplaces.com/>
77
78
79
80