/ 
Class-User-DBI-0.10
River stage zero No dependents
/ Class::User::DBI::Roles

NAME

Class::User::DBI::Roles - A Roles class.

VERSION

Version 0.10

SYNOPSIS

Through a DBIx::Connector object, this module models a "Roles" class, used for Roles Based Access Control. Class::User::DBI allows each user to have a single role. Class::User::DBI::RolePrivileges allows each role to have multiple privileges. And so goes the heirarchy: A user has a role, and a role has privileges.

# Set up a connection using DBIx::Connector:
# MySQL database settings:

my $conn = DBIx::Connector->new(
    'dbi:mysql:database=cudbi_tests, 'testing_user', 'testers_pass',
    {
        RaiseError => 1,
        AutoCommit => 1,
    }
);


# Now we can play with Class::User::DBI::Roles

# Set up a 'roles' table in the database.
Class::User::DBI::Roles->configure_db( $conn );

my $r = Class::User::DBI::Roles->new( $conn );

$r->add_roles( 
    [ 'office', 'Office users'  ],
    [ 'admin',  'Administrator' ],
);

print "Role exists." if $r->exists_role( 'office' );

my @roles = $r->fetch_roles;
foreach my $role ( @roles ) {
    my( $name, $description ) = @{$role};
    print "$name => $description\n";
}

print "Description for 'office' role: ", 
      $r->get_role_description( 'office' );

$r->set_role_description( 'office', 'Office staff' );

$r->delete_roles( 'office' ); # Pass a list for multiple deletes.

DESCRIPTION

This is a maintenance class facilitating the creation, deletion, and testing of roles that are compatible with Class::User::DBI's roles, and Class::User::DBI::RolePrivileges roles.

A common usage is to configure a database table, and then add a few roles along with their descriptions. Think of roles as similar to Unix 'groups'. Then use Class::User::DBI::Priviliges to create a few privileges. Next use Class::User::DBI::RolePrivileges to associate one or more privileges with a given role. Finally, use Class::User::DBI to associate a role with one or more users.

Class::User::DBI::RolePrivileges provides accessors to query whether a role has a given privilege. Class::User::DBI provides a means to query whether a user has a role. As a convenience, Class::User::DBI also provides an accessor to the RolePrivileges class for quickly drilling through from the user to the privilege.

EXPORT

Nothing is exported. There are many object methods, and three class methods, described in the next section.

SUBROUTINES/METHODS

new (The constructor -- Class method.)

my $role_obj = Class::User::DBI::Roles->new( $connector );

Creates a role object that can be manipulated to set and get roles from the database's 'cud_roles' table. Pass a DBIx::Connector object as a parameter. Throws an exception if it doesn't get a valid DBIx::Connector.

configure_db (Class method)

Class::User::DBI::Roles->configure_db( $connector );

This is a class method. Pass a valid DBIx::Connector as a parameter. Builds a minimal database table in support of the Class::User::DBI::Roles class.

The table created will be cud_roles.

add_roles

$r->add_roles( [ 'office', 'The office staff' ], ... );

Add one or more roles. Each role must be bundled along with its description in an array ref. Pass an AoA for multiple roles, or just an aref for a single role/description pair.

It will drop requests to add roles that already exist.

Returns a count of roles added, which may be less than the number passed if one already existed.

delete_roles

$r->delete_roles( 'office', 'sales' );

Deletes from the database all roles specified. Return value is the number of roles actually deleted, which may be less than the number of roles requested if any of the requested roles didn't exist in the database to begin with.

exists_role

print "Role exists." if $r->exists_role( 'office' );

Returns true if a given role exists, and false if not.

fetch_roles

foreach my $role ( $r->fetch_roles ) {
    print "$role->[0] = $role->[1]\n";
}

Returns an array of array refs. Each array ref contains the role's name and its description as the first and second elements, respectively.

An empty list means there are no roles defined.

get_role_description

my $description = $r->get_role_description( 'office' );

Returns the description for a given role. Throws an exception if the role doesn't exist, so be sure to test with $r->exists_role( 'office' ) first.

set_role_description

$r->set_role_description( 'office', 'New description for office role.' );

Sets a new description for a given role. If the role doesn't exist in the database, if not enough parameters are passed, or if any of the params are undef, an exception will be thrown. To update a role by giving it a blank description, pass an empty string as the description.

DEPENDENCIES

The dependencies for this module are the same as for Class::User::DBI, from this same distribution. Refer to the documentation in that module for a full description.

CONFIGURATION AND ENVIRONMENT

Please refer to the configure_db() class method for this module for a simple means of creating the table that supports this class.

All SQL for this distribution is contained in the Class::User::DBI::DB module.

DIAGNOSTICS

If you find that your particular database engine is not playing nicely with the test suite from this module, it may be necessary to provide the database login credentials for a test database using the same engine that your application will actually be using. You may do this by setting $ENV{CUDBI_TEST_DSN}, $ENV{CUDBI_TEST_DATABASE}, $ENV{CUDBI_TEST_USER}, and $ENV{CUDBI_TEST_PASS}.

Currently the test suite tests against a SQLite database since it's such a lightweight dependency for the testing. The author also uses this module with several MySQL databases. As you're configuring your database, providing its credentials to the tests and running the test scripts will offer really good diagnostics if some aspect of your database tables proves to be at odds with what this module needs.

INCOMPATIBILITIES

This module has only been tested on MySQL and SQLite database engines. If you are successful in using it with other engines, please send me an email detailing any additional configuration changes you had to make so that I can document the compatibility, and improve the documentation for the configuration process.

BUGS AND LIMITATIONS

AUTHOR

David Oswald, <davido at cpan.org>

BUGS

Please report any bugs or feature requests to bug-class-user-dbi at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-User-DBI. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Class::User::DBI::Roles

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2012 David Oswald.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.