The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Class-User-DBI-0.10
River stage zero No dependents
1 ++
/ Class::User::DBI::RolePrivileges

NAME

Class::User::DBI::RolePrivileges - A user roles and privileges class.

VERSION

Version 0.10

SYNOPSIS

Through a DBIx::Connector object, this module models a class of privileges belonging to roles.

    # 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::RolePrivileges

    # Set up a 'role-privileges' table in the database.
    Class::User::DBI::RolePrivileges->configure_db( $conn );
    
    # Instantiate a "worker_role" role so that we can manipulate its privileges.
    my $rp = Class::User::DBI::Privileges->new( $conn, 'worker_role' );

    $rp->add_privileges( 'work', 'play' ); # This role can work and play.

    print "Workers can play.\n" if $rp->has_privilege( 'play' );

    my @privileges = $rp->fetch_privileges;
    foreach my $privilege ( @privileges ) {
        print "Workers can $privilege\n";
    }
    
    $rp->delete_privileges( 'work' ); # Pass a list for multiple deletes.

DESCRIPTION

This is a maintenance class facilitating the creation, deletion, and testing of privileges belonging to a role.

A common usage is to configure a 'cud_roleprivileges' database table, and then add a few role => privilege pairs. Privileges are authorizations that a given role (group) may have. Using Class::User::DBI::Roles you have set up a list of roles and their descriptions. Using Class::User::DBI::Privileges you have set up a list of privileges and their descriptions. Now this class allows you to assign one or more of those privileges to the defined roles.

Next, Class::User::DBI may be used to assign a role to a user. Finally, the user object may be queried to determine if a user has a given privilege (by his association with his assigned role).

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_priv_obj = Class::User::DBI::RolePrivileges->new( $connector, $role );

Creates a role-privileges object that can be manipulated to set and get privileges for the instantiated role. These role/privilege pairs will be stored in a database table named cud_roleprivileges. Throws an exception if it doesn't get a valid DBIx::Connector or a valid role (where valid means the role exists in the roles table managed by Class::User::DBI::Roles.

configure_db (Class method)

    Class::User::DBI::RolePrivileges->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::Privileges class.

The table created will be cud_roleprivileges.

add_privileges

    $rp->add_privileges( 'goof_off', 'work', ... );

Add one or more privileges. Each privilege must match a privilege that lives in the privileges database, managed by Class::User::DBI::Privileges.

It will drop requests to add privileges that already exist for a given role.

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

delete_privileges

    $rp->delete_privileges( 'goof_off', 'play' ); # Now we can only work.

Deletes from the role all privileges specified. Return value is the number of privileges actually deleted, which may be less than the number of privileges requested if any of the requested privileges don't exist for the object's target role.

has_privilege

    print "This role has the 'work' privilege." 
        if $rp->has_privilege( 'work' );

Returns true if a given privilege exists for the object's target role, and false if not.

fetch_privileges

    foreach my $priv ( $rp->fetch_privileges ) {
        print "Role has $priv privilege\n";
    }

Returns a list of privileges belonging to the object's target role.

An empty list means there are no privileges defined for this role.

get_role

    my $role = $rp->get_role;

Just an accessor for reading the object's target role name.

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::RolePrivileges

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.